ParallelKit.ps1

# ParallelKit - parallel runspace jobs, bounded external-process dispatch, and
# graceful Ctrl+C/window-close handling for Windows PowerShell 5.1.
#
# Version 2.3 - https://github.com/HalRiveria/PowerShell-ParallelKit
# Copyright (c) 2026 HalRiveria. MIT License: keep this notice with any copy;
# the full text is in LICENSE in the repository.
#
# Use:   . "<path>\ParallelKit.ps1"     (dot-source it; it loads itself as an in-memory module)
# Read README.md first - the two worker-code rules there are what keep this
# from hanging or crashing.
#
# Works under Set-StrictMode: job hashtables are read as $job['Name'], never
# $job.Name, because under strict mode the dot form THROWS for a key that
# isn't there yet. Keep it that way when editing.
#
# State lives in the static [PkState] class, never in $script: variables - a
# function called from inside a .GetNewClosure()'d block can see an empty
# $script: scope, and a static has no scope to lose.

# Everything below needs Add-Type, which Constrained Language Mode blocks with
# an error that doesn't say why. Say why.
if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') {
    throw ("ParallelKit: this PowerShell session runs in " + $ExecutionContext.SessionState.LanguageMode + " mode, but the kit needs FullLanguage " +
        "(it compiles C# with Add-Type). This is usually set by AppLocker or Windows Defender Application Control policy. " +
        "Ask whoever manages the machine to allow this script, or run it where that policy doesn't apply.")
}

# Everything below loads as an in-memory module named ParallelKit. The kit's
# own frames then live in the module's session state, so a callback you pass
# in sees your variables, never the kit's locals, and the internal helpers
# stay out of your session. The public functions are imported globally, so
# they work from any .GetNewClosure() block and for the rest of the session.
# A copy loaded earlier in this session is dropped first, so only one is
# listed. -ErrorAction Stop: without it, a throw in the module body (the
# stale-types check below, say) wouldn't stop the script that loads the kit.
Get-Module -Name ParallelKit | Remove-Module
New-Module -Name ParallelKit -ErrorAction Stop -ScriptBlock {

# ==============================================================================
#  Native types (guarded so the file can be dot-sourced more than once)
# ==============================================================================

if (-not ([System.Management.Automation.PSTypeName]'PkConsoleCtrl').Type) {
    Add-Type -TypeDefinition @'
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Threading;

public static class PkConsoleCtrl
{
    public delegate bool HandlerRoutine(uint ctrlType);

    [DllImport("kernel32.dll", SetLastError = true)]
    public static extern bool SetConsoleCtrlHandler(HandlerRoutine handler, bool add);

    // Set by the handler (or Request-PkAbort); polled by PowerShell code.
    public static volatile bool AbortRequested = false;
    public static volatile bool IsCloseEvent   = false;   // true = window close/logoff/shutdown, false = Ctrl+C

    // The handler only intercepts while a run is active. Outside a run,
    // Ctrl+C and closing the window behave exactly as they normally would.
    public static volatile bool RunActive = false;

    // On a window close, logoff or shutdown the handler parks on this until
    // the run ends: the process dies as soon as the handler returns, and
    // Windows ends it after a few seconds anyway. Ctrl+C never parks.
    public static readonly ManualResetEventSlim DrainComplete = new ManualResetEventSlim(false);
    public static int DrainWaitMs = 65000;

    // Ctrl+C presses: the first starts the abort, the next skips the drain
    // (force-stops running jobs now), the one after that is let through to
    // PowerShell, which stops the script. A press within SkipDebounceMs of
    // the last counted one is a double tap or key repeat, and is ignored.
    public static volatile bool SkipDrain = false;
    public static volatile string PressedKey = null;   // "Ctrl+C" / "Ctrl+Break" once a press started the abort
    public static int SkipDebounceMs = 1000;
    private static long _lastPressTimestamp = 0;
    private static readonly object _pressLock = new object();

    private static HandlerRoutine _handler;   // strong ref so the GC can't collect it
    public static bool LastRegisterSucceeded = false;

    public static void Register()
    {
        // SetConsoleCtrlHandler is additive - drop the previous delegate
        // first so a second Register() can't leave an unrooted one behind.
        if (_handler != null) { SetConsoleCtrlHandler(_handler, false); }
        _handler = new HandlerRoutine(Handler);
        LastRegisterSucceeded = SetConsoleCtrlHandler(_handler, true);
    }

    private static bool Handler(uint ctrlType)
    {
        // 0=CTRL_C, 1=CTRL_BREAK, 2=CTRL_CLOSE, 5=CTRL_LOGOFF, 6=CTRL_SHUTDOWN
        if (!RunActive) { return false; }
        if (ctrlType == 0 || ctrlType == 1)
        {
            // Never park here: Windows delivers one console event at a time, so
            // a parked Ctrl+C would hold back the next press and a window close.
            return OnInterrupt(ctrlType == 1 ? "Ctrl+Break" : "Ctrl+C");
        }
        if (ctrlType == 2 || ctrlType == 5 || ctrlType == 6)
        {
            // IsCloseEvent BEFORE AbortRequested: a poller that sees
            // AbortRequested must already see the right IsCloseEvent.
            IsCloseEvent   = true;
            AbortRequested = true;
            DrainComplete.Wait(DrainWaitMs);
            return true;   // suppress the default OS action
        }
        return false;
    }

    // One Ctrl+C/Ctrl+Break press during a run. Public so tests can press it.
    // true = handled here; false = let PowerShell's own Ctrl+C stop the script.
    public static bool OnInterrupt(string key)
    {
        lock (_pressLock)
        {
            long now = System.Diagnostics.Stopwatch.GetTimestamp();
            if (!AbortRequested)
            {
                PressedKey = key;
                _lastPressTimestamp = now;
                AbortRequested = true;
                return true;
            }
            // An abort is already under way (this press, Request-PkAbort or a
            // close). A press that follows a counted one too closely is ignored.
            if (_lastPressTimestamp != 0)
            {
                double sinceLastMs = (now - _lastPressTimestamp) * 1000.0 / System.Diagnostics.Stopwatch.Frequency;
                if (sinceLastMs < SkipDebounceMs) { return true; }
            }
            _lastPressTimestamp = now;
            if (!SkipDrain) { SkipDrain = true; return true; }
            return false;
        }
    }

    public static void ResetPresses()
    {
        lock (_pressLock)
        {
            SkipDrain = false;
            PressedKey = null;
            _lastPressTimestamp = 0;
        }
    }
}

// Keeps the PC from idle-sleeping while a run is going. Per-thread: lifted
// by the same thread that set it, and dropped by Windows if the process ends.
public static class PkSleepBlock
{
    [DllImport("kernel32.dll")]
    private static extern uint SetThreadExecutionState(uint esFlags);
    public static bool Block()   { return SetThreadExecutionState(0x80000000u | 0x00000001u) != 0; }
    public static bool Unblock() { return SetThreadExecutionState(0x80000000u) != 0; }
}

// Main-thread bookkeeping. Static on purpose - see the note at the top of
// ParallelKit.ps1.
public static class PkState
{
    public static bool AbortLatched = false;
    public static bool CloseAbort   = false;
    public static object MessageHandler = null;   // a PowerShell scriptblock, or null for the default
    public static volatile bool ThreadPoolRaised = false;

    // Bump this whenever any C# in this file changes. A PowerShell session
    // keeps compiled types until it exits, so re-loading an edited kit into
    // an old session would silently run the OLD C# - the check after the
    // type definitions catches that. That check compares against this
    // number too; bump both together.
    public const int TypesVersion = 4;

    // Locked: Register-/Unregister-PkCancellationSource are callable from
    // worker runspaces, and List<T> is not safe for concurrent writers.
    private static readonly List<CancellationTokenSource> _sources = new List<CancellationTokenSource>();
    private static readonly object _sourcesLock = new object();

    public static void AddSource(CancellationTokenSource cts) { lock (_sourcesLock) { _sources.Add(cts); } }
    public static bool RemoveSource(CancellationTokenSource cts) { lock (_sourcesLock) { return _sources.Remove(cts); } }
    public static CancellationTokenSource[] SnapshotSources() { lock (_sourcesLock) { return _sources.ToArray(); } }
    public static int SourceCount { get { lock (_sourcesLock) { return _sources.Count; } } }
}
'@ -Language CSharp
}

if (-not ([System.Management.Automation.PSTypeName]'PkConsoleQuickEdit').Type) {
    Add-Type -TypeDefinition @'
using System;
using System.Runtime.InteropServices;

// Console QuickEdit mode freezes the whole process while the user has text
// selected. Invoke-PkRun turns it off for the length of a run.
public static class PkConsoleQuickEdit
{
    private const int STD_INPUT_HANDLE = -10;
    private const uint ENABLE_QUICK_EDIT_MODE = 0x0040;
    private const uint ENABLE_EXTENDED_FLAGS  = 0x0080;

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern IntPtr GetStdHandle(int nStdHandle);

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern bool GetConsoleMode(IntPtr hConsoleHandle, out uint lpMode);

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern bool SetConsoleMode(IntPtr hConsoleHandle, uint dwMode);

    // 1 = on, 0 = off, -1 = can't tell (no real console).
    public static int GetEnabled()
    {
        IntPtr handle = GetStdHandle(STD_INPUT_HANDLE);
        if (handle == IntPtr.Zero || handle == new IntPtr(-1)) { return -1; }
        uint mode;
        if (!GetConsoleMode(handle, out mode)) { return -1; }
        return (mode & ENABLE_QUICK_EDIT_MODE) != 0 ? 1 : 0;
    }

    public static bool SetEnabled(bool enabled)
    {
        IntPtr handle = GetStdHandle(STD_INPUT_HANDLE);
        if (handle == IntPtr.Zero || handle == new IntPtr(-1)) { return false; }
        uint mode;
        if (!GetConsoleMode(handle, out mode)) { return false; }
        if (enabled) { mode |= ENABLE_QUICK_EDIT_MODE; } else { mode &= ~ENABLE_QUICK_EDIT_MODE; }
        mode |= ENABLE_EXTENDED_FLAGS;
        return SetConsoleMode(handle, mode);
    }
}
'@ -Language CSharp
}

if (-not ([System.Management.Automation.PSTypeName]'PkChildProcessJob').Type) {
    Add-Type -TypeDefinition @'
using System;
using System.Runtime.InteropServices;

// A Windows Job Object with KILL_ON_JOB_CLOSE: every child process assigned
// to it dies when this process exits for ANY reason, force-kill included.
public static class PkChildProcessJob
{
    private const int JobObjectExtendedLimitInformation = 9;
    private const uint JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000;

    [StructLayout(LayoutKind.Sequential)]
    private 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)]
    private struct IO_COUNTERS
    {
        public ulong ReadOperationCount, WriteOperationCount, OtherOperationCount;
        public ulong ReadTransferCount, WriteTransferCount, OtherTransferCount;
    }

    [StructLayout(LayoutKind.Sequential)]
    private 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", CharSet = CharSet.Unicode, SetLastError = true)]
    private static extern IntPtr CreateJobObject(IntPtr lpJobAttributes, string lpName);

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern bool SetInformationJobObject(IntPtr hJob, int infoClass, IntPtr lpInfo, uint cbInfoLength);

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern bool AssignProcessToJobObject(IntPtr hJob, IntPtr hProcess);

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern bool CloseHandle(IntPtr hObject);

    // Deliberately never closed: the OS closes it when this process exits,
    // and that close is what kills the children. Closing it early would
    // kill running work.
    private static IntPtr _job = IntPtr.Zero;
    private static readonly object _lock = new object();

    public static bool IsInitialized { get { return _job != IntPtr.Zero; } }
    public static int LastError { get; private set; }

    public static bool Initialize()
    {
        lock (_lock)
        {
            if (_job != IntPtr.Zero) { return true; }
            IntPtr job = CreateJobObject(IntPtr.Zero, null);
            if (job == IntPtr.Zero) { LastError = Marshal.GetLastWin32Error(); return false; }

            JOBOBJECT_EXTENDED_LIMIT_INFORMATION info = new JOBOBJECT_EXTENDED_LIMIT_INFORMATION();
            info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
            int size = Marshal.SizeOf(typeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
            IntPtr buffer = Marshal.AllocHGlobal(size);
            try
            {
                Marshal.StructureToPtr(info, buffer, false);
                if (!SetInformationJobObject(job, JobObjectExtendedLimitInformation, buffer, (uint)size))
                {
                    LastError = Marshal.GetLastWin32Error();
                    CloseHandle(job);
                    return false;
                }
            }
            finally { Marshal.FreeHGlobal(buffer); }
            _job = job;
            return true;
        }
    }

    // Never throws - a failed assignment only loses the force-kill cleanup
    // for that one process, it must not fail the work itself.
    public static bool Assign(System.Diagnostics.Process process)
    {
        if (_job == IntPtr.Zero || process == null) { return false; }
        try
        {
            if (AssignProcessToJobObject(_job, process.Handle)) { return true; }
            LastError = Marshal.GetLastWin32Error();
            return false;
        }
        catch { return false; }
    }
}
'@ -Language CSharp
}

# A session that loaded an earlier copy of this file still has that copy's
# compiled types, and they can't be replaced. Say so, instead of failing
# later with a missing-method error somewhere unrelated. Keep this number
# in sync with [PkState]::TypesVersion above.
if ((& { try { [PkState]::TypesVersion } catch { 0 } }) -ne 4) {
    throw "ParallelKit: this PowerShell session already loaded an older version of the kit, and its compiled parts can't be swapped out. Close this window and start a new one."
}

# How kit functions tell a worker runspace from the main one: in a worker
# these two globals are set by Invoke-PkRunspaceJobs; everywhere else they
# are null. Defined here so reading them is legal under Set-StrictMode.
if (-not (Test-Path -LiteralPath 'Variable:\global:PkWorkerQueue')) { $global:PkWorkerQueue = $null }
if (-not (Test-Path -LiteralPath 'Variable:\global:PkCancelToken')) { $global:PkCancelToken = $null }

# ==============================================================================
#  Messages
# ==============================================================================

function Set-PkMessageHandler {
    # .SYNOPSIS
    # Sends every message the kit writes to your own scriptblock.
    # .DESCRIPTION
    # The handler gets ($Message, $Level), where Level is Info, Warn or Error, and
    # always runs on the main thread, including for messages from worker code. If it
    # throws, the message is shown on the console instead and the run carries on.
    # .PARAMETER Handler
    # { param($Message, $Level) ... }, or $null to go back to the default (console).
    # .EXAMPLE
    # Set-PkMessageHandler { param($Message, $Level) Add-Content run.log "$Level $Message" }
    [CmdletBinding()]
    param([scriptblock]$Handler)
    [PkState]::MessageHandler = $Handler
}

function Invoke-PkMessageHandler {
    # Main thread only.
    param([string]$Message, [string]$Level = 'Info')
    $handler = [PkState]::MessageHandler
    if ($null -ne $handler) {
        try {
            $null = & $handler $Message $Level   # a handler's stray output must not become our caller's output
            return
        } catch {
            # A handler that fails (a locked log file, say) must not take
            # the run down with it. Fall back to the console for this one
            # message and say why.
            Write-Host ("[ParallelKit] message handler failed (" + $_ + ") - showing the message here instead:") -ForegroundColor Yellow
        }
    }
    $color = switch ($Level) { 'Error' { 'Red' } 'Warn' { 'Yellow' } default { $null } }
    if ($color) { Write-Host $Message -ForegroundColor $color } else { Write-Host $Message }
}

function Write-PkMessage {
    # .SYNOPSIS
    # Writes a message through the kit's message handler. Safe to call from worker code.
    # .DESCRIPTION
    # In a worker runspace the message is queued and the main thread delivers it; on
    # the main thread it goes straight to the handler (see Set-PkMessageHandler).
    # .PARAMETER Message
    # The text.
    # .PARAMETER Level
    # Info (the default), Warn or Error.
    param(
        [Parameter(Mandatory)]
        [AllowEmptyString()]
        [string]$Message,
        [string]$Level = 'Info'
    )
    if ($null -ne $global:PkWorkerQueue) {
        $global:PkWorkerQueue.Enqueue(@{ Message = $Message; Level = $Level })
        return
    }
    Invoke-PkMessageHandler -Message $Message -Level $Level
}

function Receive-PkWorkerMessages {
    # Main thread only: deliver everything workers have queued so far.
    param([System.Collections.Concurrent.ConcurrentQueue[object]]$Queue)
    if ($null -eq $Queue) { return }
    $item = $null
    while ($Queue.TryDequeue([ref]$item)) {
        Invoke-PkMessageHandler -Message $item.Message -Level $item.Level
    }
}

# ==============================================================================
#  Abort handling
# ==============================================================================

function Register-PkAbortHandler {
    [PkConsoleCtrl]::Register()
    if (-not [PkConsoleCtrl]::LastRegisterSucceeded) {
        Invoke-PkMessageHandler -Level Warn -Message "[WARNING] Could not register the Ctrl+C/window-close handler - aborting a run may not drain gracefully (Ctrl+C will use the OS default action instead)."
    }
    return [PkConsoleCtrl]::LastRegisterSucceeded
}

function Initialize-PkChildProcessJob {
    if ([PkChildProcessJob]::Initialize()) { return $true }
    Invoke-PkMessageHandler -Level Warn -Message ("[WARNING] Could not set up child-process cleanup (Win32 error " + [PkChildProcessJob]::LastError + ") - if this window is force-closed mid-run, a running child process may be left behind and need ending in Task Manager.")
    return $false
}

function Initialize-PkThreadPool {
    # Every redirected child process holds two thread-pool threads for its
    # async stdout/stderr reads. The pool grows slowly past its minimum, so
    # a burst of processes can leave reads waiting long enough to look like
    # a hung process. Raise the minimum up front.
    param([int]$MaxConcurrentProcesses = 0)
    $clampedProcs = [Math]::Min([Math]::Max($MaxConcurrentProcesses, 0), 16000)
    $minimumWorkerThreads = [Math]::Max(128, (2 * $clampedProcs) + 32)
    $worker = 0; $io = 0
    [System.Threading.ThreadPool]::GetMinThreads([ref]$worker, [ref]$io)
    [PkState]::ThreadPoolRaised = $true
    if ($worker -ge $minimumWorkerThreads) { return $true }
    return [System.Threading.ThreadPool]::SetMinThreads($minimumWorkerThreads, $io)
}

function Initialize-ParallelKit {
    # .SYNOPSIS
    # Sets up Ctrl+C handling, child-process cleanup and the thread pool up front. Optional.
    # .DESCRIPTION
    # The engines set up what they need on first use anyway. Safe to call more than
    # once. A failed Ctrl+C handler or child-process cleanup also prints a warning.
    # .PARAMETER MaxConcurrentProcesses
    # How many programs you expect to run at once, used to size the thread pool.
    # 0 (the default) sizes it for up to about 48.
    # .OUTPUTS
    # An object with AbortHandler, ChildProcessJob and ThreadPool, each $true if that
    # part worked.
    [CmdletBinding()]
    param([int]$MaxConcurrentProcesses = 0)
    $handlerOk = Register-PkAbortHandler
    $jobOk     = Initialize-PkChildProcessJob
    $poolOk    = Initialize-PkThreadPool -MaxConcurrentProcesses $MaxConcurrentProcesses
    return [pscustomobject][ordered]@{ AbortHandler = $handlerOk; ChildProcessJob = $jobOk; ThreadPool = $poolOk }
}

function Register-PkCancellationSource {
    # .SYNOPSIS
    # Adds your own CancellationTokenSource to the set an abort cancels.
    # .DESCRIPTION
    # Every registered source is cancelled the moment an abort is detected. If an
    # abort is still in force when you register (see Reset-PkAbortState), the source
    # is cancelled straight away. A -Cts passed to Invoke-PkRunspaceJobs is
    # registered for you. Remove it with Unregister-PkCancellationSource when done.
    # .PARAMETER Cts
    # The source to cancel on an abort.

    # Cancelling a source registered while an old abort is still in force
    # matters: otherwise a later run would start normally while its workers,
    # seeing the old flag, quietly did nothing.
    param([Parameter(Mandatory)][System.Threading.CancellationTokenSource]$Cts)
    [PkState]::AddSource($Cts)
    if ([PkState]::AbortLatched) {
        try { $Cts.Cancel() } catch { }   # an already-disposed source has nothing left to cancel
    }
}

function Unregister-PkCancellationSource {
    # .SYNOPSIS
    # Removes a source added with Register-PkCancellationSource.
    # .PARAMETER Cts
    # The source to remove.
    param([Parameter(Mandatory)][System.Threading.CancellationTokenSource]$Cts)
    $null = [PkState]::RemoveSource($Cts)
}

function Reset-PkAbortState {
    # .SYNOPSIS
    # Clears a finished abort so the engines run again.
    # .DESCRIPTION
    # An abort stays in force until this is called: until then every engine returns
    # straight away with Aborted = $true. Invoke-PkRun calls it at the start of each
    # run, so you only need it to call an engine again outside Invoke-PkRun after an
    # abort.

    # Deliberately leaves RunActive alone: that belongs to Invoke-PkRun, and
    # clearing it here would disarm a run that calls this part-way through.
    [CmdletBinding()]
    param()
    [PkState]::AbortLatched = $false
    [PkState]::CloseAbort   = $false
    [PkConsoleCtrl]::AbortRequested = $false
    [PkConsoleCtrl]::IsCloseEvent   = $false
    [PkConsoleCtrl]::ResetPresses()
    [PkConsoleCtrl]::DrainComplete.Reset()
}

function Request-PkAbort {
    # .SYNOPSIS
    # Starts an abort from code, the same as the user pressing Ctrl+C.
    [CmdletBinding()]
    param()
    [PkConsoleCtrl]::AbortRequested = $true
}

function Test-PkAbortSignal {
    # .SYNOPSIS
    # Returns $true once an abort (Ctrl+C, window close, Request-PkAbort) is under way.
    # .DESCRIPTION
    # Inside Invoke-PkRun, Ctrl+C only raises a flag. A long step of your own there
    # should check this now and then and stop when it's true. On the main thread, the
    # first call after an abort also cancels every registered source and announces
    # the abort. Worker code should use Test-PkCancelRequested instead.
    # .OUTPUTS
    # [bool]
    [CmdletBinding()]
    param()
    if ($null -ne $global:PkWorkerQueue) {
        return [PkConsoleCtrl]::AbortRequested
    }

    if ([PkConsoleCtrl]::AbortRequested -and -not [PkState]::AbortLatched) {
        [PkState]::AbortLatched = $true
        [PkState]::CloseAbort   = [PkConsoleCtrl]::IsCloseEvent
        foreach ($cts in [PkState]::SnapshotSources()) {
            try { $cts.Cancel() } catch { }   # an already-disposed source has nothing left to cancel
        }
        $pressedKey = [PkConsoleCtrl]::PressedKey
        $abortMessage = if ([PkState]::CloseAbort) {
            # No drain on a close: Windows ends the process within seconds.
            "[ABORT] Window close detected - stopping current jobs now..."
        } elseif ($null -ne $pressedKey) {
            "[ABORT] " + $pressedKey + " detected - finishing current jobs, please wait... Press Ctrl+C again to stop them now."
        } elseif ([PkConsoleCtrl]::RunActive) {
            "[ABORT] Abort requested - finishing current jobs, please wait... Press Ctrl+C to stop them now."
        } else {
            "[ABORT] Abort requested - finishing current jobs, please wait..."
        }
        Invoke-PkMessageHandler -Message $abortMessage -Level Warn
    }
    return [PkState]::AbortLatched
}

function Test-PkCancelRequested {
    # .SYNOPSIS
    # For worker code: returns $true once this run is being cancelled or aborted.
    # .DESCRIPTION
    # Check it before any step that can't be undone (deleting a source file, say)
    # and skip the step if it's true: a worker that was force-stopped isn't killed,
    # and can carry on once its current .NET call returns.
    # .OUTPUTS
    # [bool]
    [CmdletBinding()]
    param()
    if ($null -ne $global:PkCancelToken -and $global:PkCancelToken.IsCancellationRequested) { return $true }
    return [PkConsoleCtrl]::AbortRequested
}

function Get-PkAbortTriggerLabel {
    # .SYNOPSIS
    # Says what started the abort: "Ctrl+C", "Ctrl+Break", "window close (X button)",
    # or "Request-PkAbort" for an abort started from code.
    # .OUTPUTS
    # [string]
    [CmdletBinding()]
    param()
    if ([PkState]::CloseAbort) { return "window close (X button)" }
    $pressedKey = [PkConsoleCtrl]::PressedKey
    if ($null -ne $pressedKey) { return $pressedKey }
    return "Request-PkAbort"
}

function Get-PkForceStopReason {
    # Why an abort is force-stopping jobs, for the engines' force-stop notice.
    param([int]$TimeoutSeconds)
    if ([PkConsoleCtrl]::IsCloseEvent) { return " now: the window is closing" }
    if ([PkConsoleCtrl]::SkipDrain)    { return " now: Ctrl+C was pressed again" }
    return (" that did not finish within " + $TimeoutSeconds + "s")
}

function Complete-PkAbortDrain {
    # Releases the native handler thread. Idempotent; safe on a run that was
    # never aborted.
    try { [PkConsoleCtrl]::DrainComplete.Set() } catch { }   # nothing useful to do if the event itself is broken
}

function Invoke-PkRun {
    # .SYNOPSIS
    # Runs a block with graceful Ctrl+C: the kit's engines wind their work down
    # instead of the script being killed.
    # .DESCRIPTION
    # Inside the block, Ctrl+C no longer kills anything by itself. It raises a flag
    # the kit's engines watch: no new work starts, running work gets time to finish,
    # and whatever is left is then stopped. A long step of your own in here must
    # check Test-PkAbortSignal now and then and stop when it's true, or Ctrl+C will
    # seem to do nothing until that step ends. Pressing Ctrl+C again, or closing the
    # window, skips the wait; a third press stops the script as Ctrl+C normally does.
    #
    # For the length of the run it also keeps the PC from idle-sleeping and turns off
    # the console's QuickEdit mode. Whatever the block outputs is passed through.
    # .PARAMETER ScriptBlock
    # The work to run.
    # .PARAMETER DisableQuickEdit
    # Turn QuickEdit off during the run (default $true). With it on, one stray click
    # starts a selection and freezes the script at its next console write.
    # .PARAMETER KeepAwake
    # Stop the PC idle-sleeping during the run (default $true). The display can
    # still turn off.
    # .EXAMPLE
    # $batch = Invoke-PkRun { Invoke-PkProcessBatch -Commands $commands -MaxConcurrent 6 }
    param(
        [Parameter(Mandatory)]
        [scriptblock]$ScriptBlock,
        [bool]$DisableQuickEdit = $true,
        # Stop the PC idle-sleeping for the length of the run (the display
        # can still turn off; lid close / Start -> Sleep still work).
        [bool]$KeepAwake = $true
    )
    # Already inside a run (a helper that brackets its own work, called
    # from a bracketed caller): just run it. Re-arming here would wipe the
    # outer run's abort state, and disarming on the way out would leave the
    # rest of the outer run unprotected.
    if ([PkConsoleCtrl]::RunActive) {
        & $ScriptBlock
        return
    }
    if (-not [PkConsoleCtrl]::LastRegisterSucceeded) { $null = Register-PkAbortHandler }
    if (-not [PkChildProcessJob]::IsInitialized)     { $null = Initialize-PkChildProcessJob }
    Reset-PkAbortState
    [PkConsoleCtrl]::RunActive = $true
    # Only turn QuickEdit back on afterwards if it was on to begin with.
    $quickEditWasOn = ([PkConsoleQuickEdit]::GetEnabled() -eq 1)
    if ($DisableQuickEdit -and $quickEditWasOn) { $null = [PkConsoleQuickEdit]::SetEnabled($false) }
    if ($KeepAwake) { $null = [PkSleepBlock]::Block() }
    try {
        & $ScriptBlock
    } finally {
        if ($KeepAwake) { $null = [PkSleepBlock]::Unblock() }
        if ($DisableQuickEdit -and $quickEditWasOn) { $null = [PkConsoleQuickEdit]::SetEnabled($true) }
        [PkConsoleCtrl]::RunActive = $false
        Complete-PkAbortDrain
    }
}

# ==============================================================================
#  External processes (all raw .NET - safe inside workers)
# ==============================================================================

function ConvertTo-PkArgumentString {
    # .SYNOPSIS
    # Joins a list of arguments into one command line, quoted so the program gets
    # exactly that list back.
    # .DESCRIPTION
    # An argument with a space, tab, newline or quote is wrapped in quotes, its
    # quotes become \", and backslashes are doubled where they come before a quote.
    # These are the C runtime's rules, which most Windows programs use; cmd.exe /c
    # parses its own way. An argument with one of & | < > ^ ( ) , ; is quoted
    # too, so a .bat or .cmd program, which runs through cmd.exe, gets it as one
    # argument instead of cmd acting on it. Not covered for those programs: cmd
    # expands %NAME% inside quotes, splits batch arguments at = (left unquoted,
    # since some programs read NAME=value themselves), and counts a \" as a
    # quote, so an argument containing a quote can end up partly unquoted. The
    # kit's -Arguments and Arguments values do this themselves when given a
    # list.
    # .PARAMETER Arguments
    # The arguments, in order. A $null one is left out; an empty string is passed
    # as "". A file or folder object (from Get-ChildItem or Get-Item) is its full
    # path. An element that is itself a list (or a hashtable) is an error: put
    # each argument in the outer list.
    # .OUTPUTS
    # [string]
    # .EXAMPLE
    # ConvertTo-PkArgumentString @('C:\My Files\a.png', '-o', 'C:\out\a.jxl')
    #
    # Returns: "C:\My Files\a.png" -o C:\out\a.jxl

    # .NET Framework's ProcessStartInfo has no ArgumentList, hence this.
    param(
        [Parameter(Mandatory, Position = 0)]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        # Not [string[]]: binding an array held in a variable to that turns a
        # $null element into '' before it can be left out.
        [object[]]$Arguments
    )
    $parts = [System.Collections.Generic.List[string]]::new()
    $position = 0
    foreach ($item in $Arguments) {
        $position++
        if ($null -eq $item) { continue }
        # A [string] cast would join a nested list with $OFS into one argument.
        if ($item -isnot [string] -and $item -is [System.Collections.IEnumerable]) {
            throw ("Arguments must be one string or a list of arguments, but element " + $position + " is itself a list (" + $item.GetType().Name + "). Put each argument in the outer list.")
        }
        # On 5.1 a FileInfo from Get-ChildItem casts to its bare name.
        if ($item -is [System.IO.FileSystemInfo]) { $arg = $item.FullName } else { $arg = [string]$item }
        # The C runtime only needs quotes around whitespace and quotes. The rest
        # are cmd.exe's: it runs a .bat/.cmd program's command line, acting on
        # & | < > ^ ( ) outside quotes and splitting batch arguments at , ;
        # Quoting them is harmless to other programs.
        if ($arg.Length -gt 0 -and $arg.IndexOfAny([char[]]@(' ', "`t", "`n", "`v", '"', '&', '|', '<', '>', '^', '(', ')', ',', ';')) -lt 0) {
            $parts.Add($arg)
            continue
        }
        $sb = [System.Text.StringBuilder]::new()
        $null = $sb.Append('"')
        $backslashes = 0
        foreach ($ch in $arg.ToCharArray()) {
            if ($ch -eq '\') { $backslashes++; continue }
            if ($ch -eq '"') {
                # Each backslash before a quote is doubled, then the quote escaped.
                $null = $sb.Append('\', 2 * $backslashes + 1)
                $null = $sb.Append('"')
            } else {
                if ($backslashes -gt 0) { $null = $sb.Append('\', $backslashes) }
                $null = $sb.Append($ch)
            }
            $backslashes = 0
        }
        # Trailing backslashes are doubled so they don't escape the closing quote.
        if ($backslashes -gt 0) { $null = $sb.Append('\', 2 * $backslashes) }
        $null = $sb.Append('"')
        $parts.Add($sb.ToString())
    }
    return ($parts -join ' ')
}

function Resolve-PkArguments {
    # -Arguments / Arguments as given -> the command line. A string is used as
    # written; a list is quoted one argument per element, so a path with a space
    # stays whole (a plain [string] cast would join it with spaces, or $OFS). A
    # lone file or folder object is one argument, its full path.
    param($Arguments)
    if ($null -eq $Arguments) { return '' }
    if ($Arguments -is [string]) { return $Arguments }
    if ($Arguments -is [System.Collections.IDictionary]) {
        throw ("Arguments must be one string or a list of arguments (got a " + $Arguments.GetType().Name + ").")
    }
    if ($Arguments -is [System.Collections.IEnumerable] -or $Arguments -is [System.IO.FileSystemInfo]) { return (ConvertTo-PkArgumentString -Arguments @($Arguments)) }
    return [string]$Arguments
}

function Resolve-PkEncoding {
    # -OutputEncoding as given (an Encoding, a code page number, or a name
    # like 'utf-8' or 'utf8') -> an Encoding, or $null for "not set".
    param($Encoding)
    if ($null -eq $Encoding -or ($Encoding -is [string] -and $Encoding -eq '')) { return $null }
    if ($Encoding -is [System.Text.Encoding]) { return $Encoding }
    # .NET Framework doesn't know the name 'utf8'; no BOM either way, since
    # this only decodes.
    if ($Encoding -is [string] -and $Encoding -in @('utf8', 'utf-8')) { return [System.Text.UTF8Encoding]::new($false) }
    try {
        if ($Encoding -is [int]) { return [System.Text.Encoding]::GetEncoding([int]$Encoding) }
        return [System.Text.Encoding]::GetEncoding([string]$Encoding)
    } catch {
        throw ("OutputEncoding '" + $Encoding + "' isn't an encoding .NET knows. Use a name like 'utf-8' or 'windows-1252', or a code page number like 65001.")
    }
}

function Resolve-PkFileSystemPath {
    # A path the way PowerShell reads it, turned into one Windows can use:
    # relative to the current location, or on a drive like Data:\ or ~.
    # Anything that isn't a file-system path to PowerShell (relative while
    # the current location is HKLM:, say) is taken relative to $Here, the
    # last file-system location.
    param([string]$Path, [string]$Here, [System.Management.Automation.SessionState]$CallerState)
    # Only a complete path goes straight through. \tools and C:tools depend on
    # a current drive and folder, which are PowerShell's here, not the process's.
    if ($Path -match '^([A-Za-z]:[\\/]|[\\/]{2})') { return $Path }
    $lookupFailed = $false
    try {
        $provider = $null
        $drive = $null
        $resolved = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path, [ref]$provider, [ref]$drive)
        if ($provider.Name -eq 'FileSystem') { return $resolved }
    } catch { $lookupFailed = $true }
    # A drive this module can't see: New-PSDrive inside the caller's function
    # makes one visible only from that function. Ask again from there, the
    # way Get-PkCallerFunction does (see its notes on InvokeScript).
    if ($lookupFailed -and $null -ne $CallerState) {
        $q = [string][char]39
        $text = @'
& {
    $pkProvider = $null
    $pkDrive = $null
    # Swallowed: a path the caller's scope can't read either falls back below.
    try {
        $pkResolved = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath(__PATH__, [ref]$pkProvider, [ref]$pkDrive)
        if ($pkProvider.Name -eq 'FileSystem') { $pkResolved }
    } catch { }
}
'@
        $text = $text.Replace('__PATH__', $q + [System.Management.Automation.Language.CodeGeneration]::EscapeSingleQuotedStringContent($Path) + $q)
        $hit = @($ExecutionContext.InvokeCommand.InvokeScript($CallerState, [scriptblock]::Create($text), @()))
        if ($hit.Count -gt 0) { return [string]$hit[0] }
    }
    # \tools while the current location is HKLM:, say: the root of that last
    # file-system location's drive, not the process's.
    if ($Path -match '^[\\/]') { return [System.IO.Path]::Combine([System.IO.Path]::GetPathRoot($Here), $Path.TrimStart('\', '/')) }
    # Not a path PowerShell can read (an unknown drive, say): this folder is the best guess.
    return [System.IO.Path]::Combine($Here, $Path)
}

function Start-PkProcess {
    # .SYNOPSIS
    # Starts one program hidden, with its output captured in the background.
    # .DESCRIPTION
    # The output is read as it arrives, so a chatty program can't stall on a full
    # pipe. The program is tied to the script and dies if the script is killed.
    # Pass what this returns to Wait-PkProcess and Complete-PkProcess. Throws if the
    # program can't be started.
    # .PARAMETER FilePath
    # The program to run. A path with a folder in it is read as PowerShell reads
    # paths: .\tool.exe and bin\tool.exe are relative to your current location, and
    # drives like Data:\ or ~ work. A bare name (tool.exe) is found the way Windows
    # finds programs, mostly on PATH.
    # .PARAMETER Arguments
    # Its command line: one string, passed exactly as written, or a list, each
    # element one argument, quoted for you (see ConvertTo-PkArgumentString).
    # .PARAMETER WorkingDirectory
    # Where to run it. Default: your current location. Read as PowerShell reads
    # paths, so a relative path is relative to your current location, and drives
    # like Data:\ or ~ work.
    # .PARAMETER OutputEncoding
    # How to decode its output: a name like 'utf-8', a code page number, or a
    # [System.Text.Encoding]. Default: the console's code page.
    # .OUTPUTS
    # A hashtable @{ Proc; StdoutTask; StderrTask; Stopwatch }.
    param(
        [Parameter(Mandatory)]
        [string]$FilePath,
        $Arguments = "",
        [string]$WorkingDirectory = "",
        $OutputEncoding = $null
    )
    return (Start-PkProcessCore -FilePath $FilePath -Arguments $Arguments -WorkingDirectory $WorkingDirectory -OutputEncoding $OutputEncoding -CallerState $PSCmdlet.SessionState)
}

function Start-PkProcessCore {
    # Start-PkProcess's body. -CallerState is the session of whoever called the
    # kit's public function, for paths only visible from there: the engines
    # start programs from deep inside the module, where $PSCmdlet no longer
    # leads back to the caller. Called by Start-PkProcess,
    # Invoke-PkProcessWithTimeout, the dispatcher's default starter and the batch.
    param(
        [Parameter(Mandatory)]
        [string]$FilePath,
        $Arguments = "",
        [string]$WorkingDirectory = "",
        $OutputEncoding = $null,
        [System.Management.Automation.SessionState]$CallerState
    )
    $encoding = Resolve-PkEncoding -Encoding $OutputEncoding
    $commandLine = Resolve-PkArguments -Arguments $Arguments
    # Self-starting: a caller who never ran Initialize-ParallelKit still
    # gets children that die with the script, and output reads that
    # aren't starved of threads. Both are cheap no-ops once done.
    if (-not [PkChildProcessJob]::IsInitialized) { $null = [PkChildProcessJob]::Initialize() }
    if (-not [PkState]::ThreadPoolRaised)        { $null = Initialize-PkThreadPool }

    $psi = [System.Diagnostics.ProcessStartInfo]::new()
    $psi.FileName               = $FilePath
    $psi.Arguments              = $commandLine
    $psi.UseShellExecute        = $false
    if ($null -ne $encoding) {
        $psi.StandardOutputEncoding = $encoding
        $psi.StandardErrorEncoding  = $encoding
    }
    $psi.RedirectStandardOutput = $true
    $psi.RedirectStandardError  = $true
    $psi.CreateNoWindow         = $true

    # Relative paths mean your current location, as everywhere else in
    # PowerShell, not the process's working directory (which cd and
    # Set-Location never change). From a location that isn't on disk (HKLM:,
    # say) that's the last file-system one. If that folder is gone, fall back
    # to the process's working directory, as before.
    $here = $ExecutionContext.SessionState.Path.CurrentFileSystemLocation.ProviderPath
    if (-not [System.IO.Directory]::Exists($here)) { $here = $null }

    # In a try/catch on purpose: a bare .NET call that throws does not
    # reliably stop a PowerShell script, and a $null process left behind
    # would be polled forever. The path handling is in here too: it throws
    # on a path with characters Windows doesn't allow.
    try {
        if ($WorkingDirectory) {
            if ($null -ne $here) { $WorkingDirectory = Resolve-PkFileSystemPath -Path $WorkingDirectory -Here $here -CallerState $CallerState }
            $psi.WorkingDirectory = $WorkingDirectory
        } elseif ($null -ne $here) {
            $psi.WorkingDirectory = $here
        }
        # Only a path with a folder or drive in it: a bare name is left to
        # Windows' own search, which looks on PATH.
        if ($null -ne $here -and ($FilePath.Contains('\') -or $FilePath.Contains('/') -or $FilePath.Contains(':'))) {
            $psi.FileName = Resolve-PkFileSystemPath -Path $FilePath -Here $here -CallerState $CallerState
        }
        $proc = [System.Diagnostics.Process]::Start($psi)
    } catch {
        $tried = ""
        if ($psi.FileName -ne $FilePath) { $tried = " (" + $psi.FileName + ")" }
        # The original goes along as the inner exception: the batch reads Windows' error code from it.
        throw [System.Management.Automation.RuntimeException]::new("Start-PkProcess: could not start '" + $FilePath + "'" + $tried + ": " + $_, $_.Exception)
    }
    $null = [PkChildProcessJob]::Assign($proc)
    return @{
        Proc       = $proc
        StdoutTask = $proc.StandardOutput.ReadToEndAsync()
        StderrTask = $proc.StandardError.ReadToEndAsync()
        Stopwatch  = [System.Diagnostics.Stopwatch]::StartNew()
    }
}

function Stop-PkProcessTree {
    # .SYNOPSIS
    # Kills one or more programs and every program they started.
    # .DESCRIPTION
    # Uses one taskkill /T call for all of them, so none is left running and
    # holding a program's output open; falls back to killing each program
    # directly.
    # .PARAMETER Process
    # The program(s), such as the Proc that Start-PkProcess returns.
    # .OUTPUTS
    # [bool] For one program, $true if this call killed it and $false if it
    # had already exited. For several, $true if this call killed any of them.
    param(
        [Parameter(Mandatory)]
        [AllowEmptyCollection()]
        [System.Diagnostics.Process[]]$Process
    )
    $alive = [System.Collections.Generic.List[System.Diagnostics.Process]]::new()
    foreach ($p in $Process) { if ($null -ne $p -and -not $p.HasExited) { $alive.Add($p) } }
    if ($alive.Count -eq 0) { return $false }
    $killed = $false
    $pidArgs = foreach ($p in $alive) { '/PID ' + $p.Id }
    $psi = [System.Diagnostics.ProcessStartInfo]::new((Join-Path $env:SystemRoot 'System32\taskkill.exe'), ('/T /F ' + ($pidArgs -join ' ')))
    $psi.UseShellExecute = $false
    $psi.CreateNoWindow = $true
    $psi.RedirectStandardOutput = $true
    $psi.RedirectStandardError = $true
    try {
        $taskkill = [System.Diagnostics.Process]::Start($psi)
        try {
            if ($taskkill.WaitForExit(10000)) { $killed = ($taskkill.ExitCode -eq 0) }
        } finally { $taskkill.Dispose() }
    } catch { }  # taskkill missing or blocked: the fallback below still kills each process itself
    # With several PIDs taskkill reports failure if any one was already gone
    # (it exited, or was a child in another listed tree) even when it killed
    # the rest; count it as killing them if any listed process is now gone.
    if (-not $killed -and $alive.Count -gt 1) {
        foreach ($p in $alive) { if ($p.HasExited) { $killed = $true; break } }
    }
    foreach ($p in $alive) {
        if (-not $p.HasExited) {
            try { $p.Kill(); $killed = $true } catch { }  # it exited between the check and the kill
        }
    }
    if ($killed) { foreach ($p in $alive) { $null = $p.WaitForExit(5000) } }
    return $killed
}

function Stop-PkJobProcesses {
    # The dispatcher's force-stop: every running job's process tree in one
    # Stop-PkProcessTree call, rather than one taskkill per job. A custom
    # starter's .Proc may not be a Process; those are skipped.
    param([System.Collections.Generic.List[hashtable]]$Jobs)
    $procs = foreach ($job in $Jobs) { if ($job['Proc'] -is [System.Diagnostics.Process]) { $job['Proc'] } }
    try { $null = Stop-PkProcessTree -Process @($procs) } catch { }  # best effort; each job is still waited on and disposed after
}

function Get-PkJobTimeLimit {
    # A dispatcher job's time limit in seconds: its own TimeoutSeconds key if it
    # has one, else the default. 0 = no limit. Throws on a bad key.
    param([hashtable]$Job, [double]$DefaultTimeoutSeconds = 0)
    $value = $Job['TimeoutSeconds']
    if ($null -eq $value) { return $DefaultTimeoutSeconds }
    $limit = 0.0
    $parsed = [double]::TryParse([string]$value, [System.Globalization.NumberStyles]::Float, [System.Globalization.CultureInfo]::InvariantCulture, [ref]$limit)
    if (-not $parsed -or [double]::IsNaN($limit) -or [double]::IsInfinity($limit) -or $limit -lt 0) {
        throw ("TimeoutSeconds must be a number of seconds, 0 (no limit) or more (got '" + $value + "').")
    }
    return $limit
}

function Stop-PkTimedOutJob {
    # Kills a dispatcher job's program tree once it passes the job's TimeLimit and
    # sets TimedOut; the poll then sees it exited and it is finalized like any
    # other. Only a .Proc that is a real Process is timed: anything else is left
    # to the job's own -JobPollCompleted.
    param([hashtable]$Job)
    $proc = $Job['Proc']
    $clock = $Job['Stopwatch']
    if ($proc -isnot [System.Diagnostics.Process] -or $clock -isnot [System.Diagnostics.Stopwatch]) { return }
    if ($proc.HasExited -or $clock.Elapsed.TotalSeconds -lt $Job['TimeLimit']) { return }
    # Only flagged if this call did the killing: a program that exited on its
    # own right at the deadline didn't time out. One try only: this runs every
    # pass, and a program that can't be killed would start a taskkill each time.
    $Job['TimeLimit'] = 0
    if (Stop-PkProcessTree -Process $proc) {
        $Job['TimedOut'] = $true
    } elseif (-not $proc.HasExited) {
        Write-PkMessage ("ProcessDispatch: a job passed its time limit, but its program (process " + $proc.Id + ") couldn't be stopped. It holds its slot until it exits.") -Level Warn
    }
}

function Wait-PkProcess {
    # .SYNOPSIS
    # Waits for a program to exit, with a timeout that can't overrun.
    # .DESCRIPTION
    # Waits on the process handle itself. Process.WaitForExit(int) also waits for
    # redirected output and can hang well past its own timeout.
    # .PARAMETER Process
    # The program, such as the Proc that Start-PkProcess returns.
    # .PARAMETER TimeoutMs
    # How long to wait, in milliseconds.
    # .OUTPUTS
    # [bool] $true if it exited in time.
    param(
        [Parameter(Mandatory)]
        [System.Diagnostics.Process]$Process,
        [Parameter(Mandatory)]
        [int]$TimeoutMs
    )
    # Same handle wrapping as Wait-PkRunningJobs.
    $waitHandle = [System.Threading.ManualResetEvent]::new($false)
    $origHandle = $waitHandle.SafeWaitHandle
    $waitHandle.SafeWaitHandle = [Microsoft.Win32.SafeHandles.SafeWaitHandle]::new($Process.Handle, $false)
    try {
        return $waitHandle.WaitOne($TimeoutMs)
    } finally {
        $waitHandle.SafeWaitHandle = $origHandle
        $waitHandle.Dispose()
    }
}

function Wait-PkRunningJobs {
    # The dispatch loop's pause: until a running program exits, the token is
    # cancelled, or TimeoutMs passes. Only programs that haven't exited are waited
    # on: a -JobPollCompleted can keep saying "not done" after the exit, and the
    # signalled handle would make every wait return at once and spin a core.
    # A job with no real process, or past the 63 handles WaitAny can hold on an STA
    # thread (one of them the token), is only noticed when the time is up. With
    # nothing to wait on, a plain sleep. Same handle wrapping as Wait-PkProcess.
    param(
        [System.Collections.Generic.List[hashtable]]$Jobs,
        [System.Threading.CancellationToken]$CancelToken,
        [int]$TimeoutMs
    )
    $waits = [System.Collections.Generic.List[System.Threading.WaitHandle]]::new()
    $origHandles = [System.Collections.Generic.List[object]]::new()
    try {
        foreach ($job in $Jobs) {
            if ($waits.Count -ge 62) { break }
            $proc = $job['Proc']
            if ($proc -isnot [System.Diagnostics.Process] -or $proc.HasExited) { continue }
            $procHandle = $proc.Handle
            $waitHandle = [System.Threading.ManualResetEvent]::new($false)
            $origHandle = $waitHandle.SafeWaitHandle
            $waitHandle.SafeWaitHandle = [Microsoft.Win32.SafeHandles.SafeWaitHandle]::new($procHandle, $false)
            $waits.Add($waitHandle)
            $origHandles.Add($origHandle)
        }
        if ($waits.Count -gt 0) {
            $waits.Add($CancelToken.WaitHandle)
            $null = [System.Threading.WaitHandle]::WaitAny($waits.ToArray(), $TimeoutMs)
            return
        }
    } catch {
        # A process that can't be read or waited on (a starter's own, say) is
        # the job's -JobPollCompleted to deal with; here it just means sleeping.
    } finally {
        for ($i = 0; $i -lt $origHandles.Count; $i++) {
            $waits[$i].SafeWaitHandle = $origHandles[$i]
            $waits[$i].Dispose()
        }
    }
    [System.Threading.Thread]::Sleep($TimeoutMs)
}

function Complete-PkProcess {
    # .SYNOPSIS
    # Collects the exit code and output of a program that has exited.
    # .DESCRIPTION
    # A program that exited can still have its output held open by a program it
    # started, so reading the output is time-limited too; StreamTimedOut says when
    # that limit was hit.
    # .PARAMETER Job
    # What Start-PkProcess returned, or a dispatcher job with the same keys.
    # .PARAMETER StreamTimeoutMs
    # How long to wait for the output after the program exits (default 15000).
    # .PARAMETER Dispose
    # Dispose the process object afterwards (default $false).
    # .OUTPUTS
    # An object with ExitCode, Stdout, Stderr, StreamTimedOut and StreamError.
    param(
        [Parameter(Mandatory)]
        [hashtable]$Job,
        [int]$StreamTimeoutMs = 15000,
        [bool]$Dispose = $false
    )
    $result = [ordered]@{ ExitCode = $null; Stdout = $null; Stderr = $null; StreamTimedOut = $false; StreamError = $null }
    # A job started by a custom starter may have no read tasks, and a read
    # can fail. Neither is worth an exception here - this runs inside
    # JobFinalize, where a throw stops the whole dispatcher.
    $tasks = [System.Collections.Generic.List[System.Threading.Tasks.Task]]::new()
    if ($null -ne $Job['StdoutTask']) { $tasks.Add($Job['StdoutTask']) }
    if ($null -ne $Job['StderrTask']) { $tasks.Add($Job['StderrTask']) }
    if ($tasks.Count -gt 0) {
        try {
            if (-not [System.Threading.Tasks.Task]::WaitAll($tasks.ToArray(), $StreamTimeoutMs)) { $result.StreamTimedOut = $true }
        } catch {
            $result.StreamError = [string]$_.Exception.Message
        }
    }
    $ranToCompletion = [System.Threading.Tasks.TaskStatus]::RanToCompletion
    if ($null -ne $Job['StdoutTask'] -and $Job['StdoutTask'].Status -eq $ranToCompletion) { $result.Stdout = $Job['StdoutTask'].Result }
    if ($null -ne $Job['StderrTask'] -and $Job['StderrTask'].Status -eq $ranToCompletion) { $result.Stderr = $Job['StderrTask'].Result }
    $result.ExitCode = $Job['Proc'].ExitCode
    if ($Dispose) { $Job['Proc'].Dispose() }
    return [pscustomobject]$result
}

function Invoke-PkProcessWithTimeout {
    # .SYNOPSIS
    # Runs one program to completion, with a hard time limit.
    # .DESCRIPTION
    # Throws if the program had to be killed: because it ran past -TimeoutMs, or
    # because the run was aborted or cancelled while it was going. Anything the
    # program started is killed with it.
    # .PARAMETER FilePath
    # The program to run.
    # .PARAMETER Arguments
    # Its command line: one string, passed exactly as written, or a list, each
    # element one argument, quoted for you (see ConvertTo-PkArgumentString).
    # .PARAMETER TimeoutMs
    # The time limit in milliseconds (default 60000).
    # .PARAMETER StreamTimeoutMs
    # How long to wait for the output after the program exits (default 15000).
    # .PARAMETER WorkingDirectory
    # Where to run it, as for Start-PkProcess. Default: your current location.
    # .PARAMETER OutputEncoding
    # How to decode its output, as for Start-PkProcess.
    # .PARAMETER IgnoreAbort
    # Keep going during an abort, for a cleanup or restore step that has to run
    # because of it.
    # .OUTPUTS
    # An object with ExitCode, Stdout, Stderr, StreamTimedOut and StreamError.
    # .EXAMPLE
    # $r = Invoke-PkProcessWithTimeout -FilePath git.exe -Arguments 'rev-parse HEAD' -TimeoutMs 10000
    param(
        [Parameter(Mandatory)]
        [string]$FilePath,
        $Arguments = "",
        [int]$TimeoutMs = 60000,
        [int]$StreamTimeoutMs = 15000,
        [string]$WorkingDirectory = "",
        $OutputEncoding = $null,
        # For a program that has to run BECAUSE of an abort (cleanup, a
        # restore step): keep going even though the run is being aborted.
        [switch]$IgnoreAbort
    )
    $job = Start-PkProcessCore -FilePath $FilePath -Arguments $Arguments -WorkingDirectory $WorkingDirectory -OutputEncoding $OutputEncoding -CallerState $PSCmdlet.SessionState
    try {
        # Wait in short slices so Ctrl+C (or the run's cancel token) is
        # noticed within a moment, not after the whole time limit.
        $waited  = [System.Diagnostics.Stopwatch]::StartNew()
        $exited  = $false
        $stopWhy = $null
        while (-not $exited) {
            $remainingMs = $TimeoutMs - [int]$waited.ElapsedMilliseconds
            if ($remainingMs -le 0) { $stopWhy = ("did not exit within " + $TimeoutMs + "ms"); break }
            $exited = Wait-PkProcess -Process $job['Proc'] -TimeoutMs ([Math]::Min(200, $remainingMs))
            if (-not $exited -and -not $IgnoreAbort -and ((Test-PkAbortSignal) -or (Test-PkCancelRequested))) { $stopWhy = "was stopped because the run is being aborted"; break }
        }
        if (-not $exited) {
            try { $null = Stop-PkProcessTree -Process $job['Proc'] } catch { }   # best effort - the throw below still reports why
            # Let the two output reads finish (the kill closes their pipes)
            # before the process is disposed under them. Bounded, and any
            # read error is irrelevant - the stop reason is what gets reported.
            try { $null = [System.Threading.Tasks.Task]::WaitAll(@($job['StdoutTask'], $job['StderrTask']), 500) } catch { }
            throw ("'" + $FilePath + "' " + $stopWhy + " - killed")
        }
        return Complete-PkProcess -Job $job -StreamTimeoutMs $StreamTimeoutMs
    } finally {
        $job['Proc'].Dispose()
    }
}

# ==============================================================================
#  Process dispatch - run many external processes, a bounded number at a time
# ==============================================================================

function Invoke-PkProcessDispatch {
    # .SYNOPSIS
    # Runs external programs grouped by unit of work (a folder, a batch), a limited
    # number at a time, with a callback when each group is done.
    # .DESCRIPTION
    # Groups are pulled one at a time from -GroupProvider; -JobBuilder turns each
    # into job hashtables; jobs run up to -MaxConcurrent at once across all groups;
    # -GroupCompleteCallback fires when a group's last job finishes. Anything your
    # callbacks output is discarded.
    #
    # The dispatcher keeps its own state on each job hashtable. Don't use these keys
    # for anything else: GroupKey, SlotReleased, Proc, StdoutTask, StderrTask,
    # Stopwatch, TimeLimit, TimedOut, StartFailureReported. It also sets Group to
    # the job's group, unless the job already has a Group of its own. The default
    # starter reads FilePath, Arguments (a string as written, or a list quoted one
    # argument per element), WorkingDirectory and OutputEncoding from the job. A
    # job's TimeoutSeconds key overrides -TimeoutSeconds.
    # .PARAMETER GroupProvider
    # { } returning the next group, or $null when there are no more.
    # .PARAMETER JobBuilder
    # { param($group) } returning the group's job hashtable(s), or @() for none.
    # .PARAMETER JobStarter
    # { param($job) } that starts the job and returns it with .Proc set. Default:
    # Start-PkProcess on the job's FilePath and Arguments.
    # .PARAMETER JobPollCompleted
    # { param($job) } returning $true once the job is finished. Default:
    # $job['Proc'].HasExited.
    # .PARAMETER JobFinalize
    # { param($job, $pendingQueue) } called once per finished job; collect its
    # result with Complete-PkProcess. Enqueue new job hashtables onto $pendingQueue
    # to retry or add follow-up work in the same group.
    # .PARAMETER JobAbortCleanup
    # { param($job) } for a job an abort killed or kept from starting, to remove its
    # partial output.
    # .PARAMETER GroupCompleteCallback
    # { param($group) } when a group's last job finishes. Also called for a group an
    # abort cut short, so check Test-PkCancelRequested before anything irreversible.
    # .PARAMETER MaxConcurrent
    # How many programs run at once: an int, or a SemaphoreSlim shared by several
    # dispatchers that must stay under one combined limit. -MaxParallel also works.
    # .PARAMETER AbortPollCallback
    # { param($runningJobs) } run on every loop pass, with the jobs currently running.
    # .PARAMETER CancelToken
    # Stops the dispatcher when cancelled. An abort stops it either way, without
    # cancelling this token.
    # .PARAMETER AbortTimeoutSeconds
    # How long an abort waits for running jobs before force-stopping them
    # (default 60). A force-stopped program is killed along with anything it
    # started. -DrainTimeoutSeconds also works.
    # .PARAMETER MaxQueueAhead
    # How many groups to pull ahead of the ones running (default 3).
    # .PARAMETER GroupReleaseCheck
    # { param($group) } returning $true to release a zero-job group's queue-ahead
    # slot; until then it holds the slot. Runs on every loop pass, so keep it cheap.
    # .PARAMETER TimeoutSeconds
    # Kill a job's program, and anything it started, still running after this long
    # (default 0, no limit). A job's own TimeoutSeconds key overrides it, and 0 there
    # opts the job out. The killed job still goes through -JobFinalize, with
    # $job['TimedOut'] = $true. A job whose .Proc isn't a process isn't timed.
    # .OUTPUTS
    # An object with GroupResults, Aborted, ForceKilledCount and
    # JobStarterFailedCount. Each group result has GroupInfo (the group), Completed
    # and Aborted.
    param(
        [Parameter(Mandatory)]
        [scriptblock]$GroupProvider,
        [Parameter(Mandatory)]
        [scriptblock]$JobBuilder,
        [scriptblock]$JobStarter = $null,
        [scriptblock]$JobPollCompleted = $null,
        [Parameter(Mandatory)]
        [scriptblock]$JobFinalize,
        [scriptblock]$JobAbortCleanup = $null,
        [scriptblock]$GroupCompleteCallback = $null,
        [Parameter(Mandatory)]
        [Alias('MaxParallel')]
        $MaxConcurrent,
        [scriptblock]$AbortPollCallback = $null,
        [System.Threading.CancellationToken]$CancelToken,
        [Alias('DrainTimeoutSeconds')]
        [int]$AbortTimeoutSeconds = 60,
        [int]$MaxQueueAhead = 3,
        [scriptblock]$GroupReleaseCheck = $null,
        [double]$TimeoutSeconds = 0
    )
    # pk-prefixed, parameters included: inside a worker runspace the kit isn't
    # a module, so a callback without .GetNewClosure() sees this frame's
    # variables. Same in Add-PkDispatchGroupJobs, Invoke-PkProcessDispatchCore, Invoke-PkProcessBatch.
    $pkGroupProvider = $GroupProvider
    $pkJobBuilder = $JobBuilder
    $pkJobStarter = $JobStarter
    $pkJobPollCompleted = $JobPollCompleted
    $pkJobFinalize = $JobFinalize
    $pkJobAbortCleanup = $JobAbortCleanup
    $pkGroupCompleteCallback = $GroupCompleteCallback
    $pkMaxConcurrent = $MaxConcurrent
    $pkAbortPollCallback = $AbortPollCallback
    $pkCancelToken = $CancelToken
    $pkAbortTimeoutSeconds = $AbortTimeoutSeconds
    $pkMaxQueueAhead = $MaxQueueAhead
    $pkGroupReleaseCheck = $GroupReleaseCheck
    $pkTimeoutSeconds = $TimeoutSeconds
    Remove-Variable -Name GroupProvider, JobBuilder, JobStarter, JobPollCompleted, JobFinalize, JobAbortCleanup, GroupCompleteCallback, MaxConcurrent, AbortPollCallback, CancelToken, AbortTimeoutSeconds, MaxQueueAhead, GroupReleaseCheck, TimeoutSeconds -Scope Local

    # 0 or less would never start a job (or pull a group) and spin forever.
    if ($pkMaxConcurrent -isnot [System.Threading.SemaphoreSlim]) {
        $pkMaxConcurrentInt = 0
        if (-not [int]::TryParse([string]$pkMaxConcurrent, [ref]$pkMaxConcurrentInt) -or $pkMaxConcurrentInt -lt 1) {
            throw ("Invoke-PkProcessDispatch: -MaxConcurrent must be a whole number of at least 1, or a SemaphoreSlim (got '" + $pkMaxConcurrent + "').")
        }
        $pkMaxConcurrent = $pkMaxConcurrentInt
    }
    if ($pkMaxQueueAhead -lt 1) { throw "Invoke-PkProcessDispatch: -MaxQueueAhead must be at least 1." }
    # Invoke-PkProcessBatch has the same check, so its error names the batch.
    if ($pkTimeoutSeconds -lt 0) { throw "Invoke-PkProcessDispatch: -TimeoutSeconds must be 0 (no limit) or more." }

    # Two pool threads per running process for its output reads - make sure
    # they exist up front. For a shared budget, the slots free right now
    # are the best available measure of its size.
    $pkPoolSizeHint = 0
    if ($pkMaxConcurrent -is [int]) { $pkPoolSizeHint = $pkMaxConcurrent }
    elseif ($pkMaxConcurrent -is [System.Threading.SemaphoreSlim]) { $pkPoolSizeHint = $pkMaxConcurrent.CurrentCount }
    $null = Initialize-PkThreadPool -MaxConcurrentProcesses $pkPoolSizeHint

    if ($null -eq $pkJobStarter) {
        $pkCallerState = $PSCmdlet.SessionState
        $pkJobStarter = {
            param($pkJob)
            $pkStarted = Start-PkProcessCore -CallerState $pkCallerState -FilePath $pkJob['FilePath'] -Arguments $pkJob['Arguments'] -WorkingDirectory ([string]$pkJob['WorkingDirectory']) -OutputEncoding $pkJob['OutputEncoding']
            $pkJob['Proc'] = $pkStarted.Proc; $pkJob['StdoutTask'] = $pkStarted.StdoutTask; $pkJob['StderrTask'] = $pkStarted.StderrTask
            $pkJob['Stopwatch'] = $pkStarted.Stopwatch
            return $pkJob
        }
    }
    # The default poll reads $pkJob['Proc'], so a started job must have one.
    $pkRequireProc = ($null -eq $pkJobPollCompleted)
    if ($null -eq $pkJobPollCompleted)      { $pkJobPollCompleted      = { param($pkJob) return $pkJob['Proc'].HasExited } }
    if ($null -eq $pkJobAbortCleanup)       { $pkJobAbortCleanup       = { param($pkJob) } }
    if ($null -eq $pkGroupCompleteCallback) { $pkGroupCompleteCallback = { param($pkGroup) } }

    # Token: the caller's; else (in a worker) the run's own; else a fresh one
    # registered so an abort cancels it.
    $pkOwnCts = $null
    if (-not $PSBoundParameters.ContainsKey('CancelToken')) {
        if ($null -ne $global:PkCancelToken) {
            $pkCancelToken = $global:PkCancelToken
        } else {
            $pkOwnCts = [System.Threading.CancellationTokenSource]::new()
            Register-PkCancellationSource -Cts $pkOwnCts
            $pkCancelToken = $pkOwnCts.Token
        }
    } else {
        # The caller's own token: nothing would cancel it on Ctrl+C. Run on
        # a linked source that an abort DOES cancel (and that still follows
        # the caller's token). In a worker it also follows the run's token,
        # so the run being cancelled for any reason stops this dispatcher.
        $pkLinkTokens = [System.Collections.Generic.List[System.Threading.CancellationToken]]::new()
        $pkLinkTokens.Add($pkCancelToken)
        if ($null -ne $global:PkCancelToken) { $pkLinkTokens.Add($global:PkCancelToken) }
        $pkOwnCts = [System.Threading.CancellationTokenSource]::CreateLinkedTokenSource($pkLinkTokens.ToArray())
        Register-PkCancellationSource -Cts $pkOwnCts
        $pkCancelToken = $pkOwnCts.Token
    }

    try {
        return Invoke-PkProcessDispatchCore -GroupProvider $pkGroupProvider -JobBuilder $pkJobBuilder -JobStarter $pkJobStarter `
            -JobPollCompleted $pkJobPollCompleted -JobFinalize $pkJobFinalize -JobAbortCleanup $pkJobAbortCleanup `
            -GroupCompleteCallback $pkGroupCompleteCallback -MaxConcurrent $pkMaxConcurrent -AbortPollCallback $pkAbortPollCallback `
            -CancelToken $pkCancelToken -AbortTimeoutSeconds $pkAbortTimeoutSeconds -MaxQueueAhead $pkMaxQueueAhead `
            -GroupReleaseCheck $pkGroupReleaseCheck -RequireProc $pkRequireProc -TimeoutSeconds $pkTimeoutSeconds
    } finally {
        if ($null -ne $pkOwnCts) {
            Unregister-PkCancellationSource -Cts $pkOwnCts
            $pkOwnCts.Dispose()
        }
    }
}

function Add-PkDispatchGroupJobs {
    # Builds one group's jobs, tags them with the group and queues them.
    # Returns how many were queued. Its own function, not inline in the
    # dispatch loop, so the group's job list dies with this call. Kept in the
    # loop's frame it stayed alive for the whole run, and with it every
    # finished job's output, even output the caller had already dropped.
    # Nulling the variables in the loop didn't help once the kit had run many
    # times in a session (most likely PowerShell's compiled code keeping its
    # own references); a separate call did.
    param(
        [Parameter(Mandatory)][scriptblock]$JobBuilder,
        $GroupInfo,
        [Parameter(Mandatory)][object]$GroupKey,
        [Parameter(Mandatory)][System.Collections.Generic.Queue[hashtable]]$Pending
    )
    # pk-prefixed, parameters included: inside a worker runspace the kit isn't
    # a module, so a callback without .GetNewClosure() sees this frame's
    # variables. Same in Invoke-PkProcessDispatch, Invoke-PkProcessDispatchCore, Invoke-PkProcessBatch.
    $pkJobBuilder = $JobBuilder
    $pkGroupInfo = $GroupInfo
    $pkGroupKey = $GroupKey
    $pkPending = $Pending
    Remove-Variable -Name JobBuilder, GroupInfo, GroupKey, Pending -Scope Local
    $pkRawJobs = & $pkJobBuilder $pkGroupInfo
    # Assigned inside each branch, NOT `$pkJobs = if (...) {...} else {...}`:
    # captured through an if/else, a single hashtable gets
    # enumerated into its key/value pairs.
    if ($null -eq $pkRawJobs) { $pkRawJobList = @() } else { $pkRawJobList = @($pkRawJobs) }
    # Keep only real job hashtables: a builder that lets a stray
    # value escape (a HashSet.Add's True, say) must not crash the run.
    $pkJobs = [System.Collections.Generic.List[hashtable]]::new()
    foreach ($pkRawJob in $pkRawJobList) { if ($pkRawJob -is [hashtable]) { $pkJobs.Add($pkRawJob) } }
    if ($pkJobs.Count -ne $pkRawJobList.Count) {
        Write-PkMessage ("ProcessDispatch: -JobBuilder returned " + ($pkRawJobList.Count - $pkJobs.Count) + " value(s) that are not job hashtables - ignored. Each job must be a hashtable.") -Level Warn
    }
    foreach ($pkJ in $pkJobs) {
        $pkJ['GroupKey'] = $pkGroupKey
        if (-not $pkJ.ContainsKey('Group')) { $pkJ['Group'] = $pkGroupInfo }   # leave a job's own 'Group' field alone
        $pkPending.Enqueue($pkJ)
    }
    return $pkJobs.Count
}

function Invoke-PkProcessDispatchCore {
    # The dispatch loop itself. Call Invoke-PkProcessDispatch, not this.
    param(
        [scriptblock]$GroupProvider,
        [scriptblock]$JobBuilder,
        [scriptblock]$JobStarter,
        [scriptblock]$JobPollCompleted,
        [scriptblock]$JobFinalize,
        [scriptblock]$JobAbortCleanup,
        [scriptblock]$GroupCompleteCallback,
        $MaxConcurrent,
        [scriptblock]$AbortPollCallback,
        [System.Threading.CancellationToken]$CancelToken,
        [int]$AbortTimeoutSeconds,
        [int]$MaxQueueAhead,
        [scriptblock]$GroupReleaseCheck,
        [bool]$RequireProc = $false,
        [double]$TimeoutSeconds = 0
    )
    # pk-prefixed, parameters included: inside a worker runspace the kit isn't
    # a module, so a callback without .GetNewClosure() sees this frame's
    # variables. Same in Add-PkDispatchGroupJobs, Invoke-PkProcessDispatch, Invoke-PkProcessBatch.
    $pkGroupProvider = $GroupProvider
    $pkJobBuilder = $JobBuilder
    $pkJobStarter = $JobStarter
    $pkJobPollCompleted = $JobPollCompleted
    $pkJobFinalize = $JobFinalize
    $pkJobAbortCleanup = $JobAbortCleanup
    $pkGroupCompleteCallback = $GroupCompleteCallback
    $pkMaxConcurrent = $MaxConcurrent
    $pkAbortPollCallback = $AbortPollCallback
    $pkCancelToken = $CancelToken
    $pkAbortTimeoutSeconds = $AbortTimeoutSeconds
    $pkMaxQueueAhead = $MaxQueueAhead
    $pkGroupReleaseCheck = $GroupReleaseCheck
    $pkRequireProc = $RequireProc
    $pkTimeoutSeconds = $TimeoutSeconds
    Remove-Variable -Name GroupProvider, JobBuilder, JobStarter, JobPollCompleted, JobFinalize, JobAbortCleanup, GroupCompleteCallback, MaxConcurrent, AbortPollCallback, CancelToken, AbortTimeoutSeconds, MaxQueueAhead, GroupReleaseCheck, RequireProc, TimeoutSeconds -Scope Local

    $pkIsSharedBudget = ($pkMaxConcurrent -is [System.Threading.SemaphoreSlim])

    $pkGroupStates      = [System.Collections.Generic.Dictionary[object,hashtable]]::new()
    $pkGroupResults     = [System.Collections.Generic.List[object]]::new()
    $pkActiveGroupCount = 0
    $pkProviderExhausted = $false
    $pkHeldGroups       = [System.Collections.Generic.List[object]]::new()

    $pkPending = [System.Collections.Generic.Queue[hashtable]]::new()
    $pkRunning = [System.Collections.Generic.List[hashtable]]::new()

    $pkDispatchResult = [ordered]@{
        GroupResults          = $pkGroupResults
        Aborted               = $false
        ForceKilledCount      = 0
        JobStarterFailedCount = 0
    }

    try {
    while ((-not $pkCancelToken.IsCancellationRequested) -and `
           (-not $pkProviderExhausted -or $pkActiveGroupCount -gt 0 -or $pkPending.Count -gt 0 -or $pkRunning.Count -gt 0)) {

        for ($pkH = $pkHeldGroups.Count - 1; $pkH -ge 0; $pkH--) {
            if ([bool](& $pkGroupReleaseCheck $pkHeldGroups[$pkH])) {
                $pkHeldGroups.RemoveAt($pkH)
                $pkActiveGroupCount--
            }
        }

        while ((-not $pkProviderExhausted) -and $pkActiveGroupCount -lt $pkMaxQueueAhead -and (-not $pkCancelToken.IsCancellationRequested)) {
            $pkGroupInfo = & $pkGroupProvider
            if ($null -eq $pkGroupInfo) { $pkProviderExhausted = $true; break }
            # A fresh object per group, NOT the group value itself: two
            # groups that compare equal (the same folder name, say) must not
            # share one job count. Jobs carry this key as .GroupKey and the
            # group value itself as .Group.
            $pkGroupKey = [object]::new()
            $pkJobCount = Add-PkDispatchGroupJobs -JobBuilder $pkJobBuilder -GroupInfo $pkGroupInfo -GroupKey $pkGroupKey -Pending $pkPending
            $pkState = @{ GroupInfo = $pkGroupInfo; Outstanding = $pkJobCount; Completed = $false }
            $pkGroupStates[$pkGroupKey] = $pkState
            $pkActiveGroupCount++
            if ($pkState.Outstanding -le 0) {
                $null = & $pkGroupCompleteCallback $pkGroupInfo
                $pkState.Completed = $true
                if ($null -ne $pkGroupReleaseCheck) { $pkHeldGroups.Add($pkGroupInfo) } else { $pkActiveGroupCount-- }
                $pkGroupResults.Add([pscustomobject][ordered]@{ GroupInfo = $pkGroupInfo; Completed = $true; Aborted = $false })
            }
        }

        # Main thread: this is what notices an abort and cancels the token.
        # Worker: just reads the flag; the main thread cancels the token.
        $null = Test-PkAbortSignal
        if ($pkAbortPollCallback) { $null = & $pkAbortPollCallback @($pkRunning) }

        while ($pkPending.Count -gt 0 -and (-not $pkCancelToken.IsCancellationRequested) -and `
               $(if ($pkIsSharedBudget) { $pkMaxConcurrent.Wait(0) } else { $pkRunning.Count -lt $pkMaxConcurrent })) {
            $pkJob = $pkPending.Dequeue()
            try {
                # Don't trust the starter's output shape: a starter that
                # forgets to return the job (or leaks other output) would
                # leave something un-pollable in $pkRunning and spin forever.
                # The running job is always the caller's own job object, so
                # the fields its builder set are still there at finalize
                # time. If the starter output a DIFFERENT hashtable (a bare
                # `Start-PkProcess ...` outputs its start result), fold that
                # one's fields into the job rather than swapping the job out.
                # A job object that has been round once already (JobFinalize
                # put the SAME object back on the queue) still carries its
                # old, disposed process - clear that before it starts again.
                if ($pkJob['SlotReleased']) {
                    $pkJob['Proc'] = $null; $pkJob['StdoutTask'] = $null; $pkJob['StderrTask'] = $null; $pkJob['Stopwatch'] = $null
                }
                $pkJob['SlotReleased'] = $false
                # Before starting, so a bad key never leaves a program running.
                $pkStartFailureText = "ProcessDispatch: a job couldn't start: "
                $pkJob['TimeLimit'] = Get-PkJobTimeLimit -Job $pkJob -DefaultTimeoutSeconds $pkTimeoutSeconds
                $pkStartFailureText = "ProcessDispatch: JobStarter failed to start a job: "
                $pkStartedRaw = & $pkJobStarter $pkJob
                foreach ($pkItem in @($pkStartedRaw)) {
                    if ($pkItem -isnot [hashtable] -or [object]::ReferenceEquals($pkItem, $pkJob)) { continue }
                    foreach ($pkItemKey in @($pkItem.Keys)) {
                        if ($null -eq $pkJob[$pkItemKey]) { $pkJob[$pkItemKey] = $pkItem[$pkItemKey] }
                    }
                }
                if ($pkRequireProc -and $null -eq $pkJob['Proc']) {
                    throw "JobStarter did not set the job's .Proc (set .Proc on the job and return it, or supply -JobPollCompleted)."
                }
                $pkJob['TimedOut'] = $false
                if ($pkJob['TimeLimit'] -gt 0 -and $null -eq $pkJob['Stopwatch']) { $pkJob['Stopwatch'] = [System.Diagnostics.Stopwatch]::StartNew() }
                $pkRunning.Add($pkJob)
            } catch {
                # Release BEFORE reporting: if reporting throws, the slot
                # would otherwise leak (this job never reached $pkRunning, so
                # the outer cleanup can't find it).
                if ($pkIsSharedBudget) { $null = $pkMaxConcurrent.Release() }
                # The batch sets this key on its own jobs: it reports start failures itself.
                if (-not $pkJob['StartFailureReported']) { Write-PkMessage ($pkStartFailureText + $_) -Level Error }
                $pkDispatchResult.JobStarterFailedCount++
                $pkKey = $pkJob['GroupKey']
                if ($pkGroupStates.ContainsKey($pkKey)) {
                    $pkState = $pkGroupStates[$pkKey]
                    $pkState.Outstanding--
                    if ($pkState.Outstanding -le 0 -and -not $pkState.Completed) {
                        $null = & $pkGroupCompleteCallback $pkState.GroupInfo
                        $pkState.Completed = $true
                        $pkActiveGroupCount--
                        $pkGroupResults.Add([pscustomobject][ordered]@{ GroupInfo = $pkState.GroupInfo; Completed = $true; Aborted = $false })
                    }
                } else {
                    Write-PkMessage ("ProcessDispatch: invariant violation - job's GroupKey is not registered (JobStarter failure path). This should be unreachable; the dispatch loop may now hang.") -Level Error
                }
            }
        }

        # ---- BLOCK: main dispatch loop's poll pass ----
        # Same poll/finalize/completion sequence as the graceful-wait loop
        # and the mandatory final pass below - keep all three in sync.
        $pkStillRunning = [System.Collections.Generic.List[hashtable]]::new()
        foreach ($pkJob in $pkRunning) {
            if ($pkJob['TimeLimit'] -gt 0) { Stop-PkTimedOutJob -Job $pkJob }
            if (& $pkJobPollCompleted $pkJob) {
                $pkPendingBefore = $pkPending.Count
                $null = & $pkJobFinalize $pkJob $pkPending
                try { if ($pkJob['Proc']) { $pkJob['Proc'].Dispose() } } catch { }   # a failed Dispose can't affect the result already taken
                if ($pkIsSharedBudget) { $null = $pkMaxConcurrent.Release() }
                $pkJob['SlotReleased'] = $true
                # Whatever JobFinalize queued (a retry, follow-up steps) is counted
                # into its group HERE, by looking at the queue - not by trusting a
                # returned flag. A flag with nothing queued would hang the group
                # forever; two follow-ups would let it finish early.
                # Only when the queue actually grew - walking it on every finished
                # job would cost a full pass over a large batch each time.
                if ($pkPending.Count -gt $pkPendingBefore) {
                    $pkQueuedIndex = 0
                    foreach ($pkQueued in $pkPending) {
                        if ($pkQueuedIndex -ge $pkPendingBefore) {
                            if ($null -eq $pkQueued['GroupKey']) { $pkQueued['GroupKey'] = $pkJob['GroupKey']; if (-not $pkQueued.ContainsKey('Group')) { $pkQueued['Group'] = $pkJob['Group'] } }
                            if ($pkGroupStates.ContainsKey($pkQueued['GroupKey'])) { $pkGroupStates[$pkQueued['GroupKey']].Outstanding++ }
                        }
                        $pkQueuedIndex++
                    }
                }
                if ($null -ne $pkJob['GroupKey']) {
                    $pkKey = $pkJob['GroupKey']
                    if ($pkGroupStates.ContainsKey($pkKey)) {
                        $pkState = $pkGroupStates[$pkKey]
                        $pkState.Outstanding--
                        if ($pkState.Outstanding -le 0 -and -not $pkState.Completed) {
                            $null = & $pkGroupCompleteCallback $pkState.GroupInfo
                            $pkState.Completed = $true
                            $pkActiveGroupCount--
                            $pkGroupResults.Add([pscustomobject][ordered]@{ GroupInfo = $pkState.GroupInfo; Completed = $true; Aborted = $false })
                        }
                    } else {
                        Write-PkMessage ("ProcessDispatch: invariant violation - job's GroupKey is not registered (main poll pass). This should be unreachable; the dispatch loop may now hang.") -Level Error
                    }
                }
            } else {
                $pkStillRunning.Add($pkJob)
            }
        }
        # A job that finished freed a slot: go straight round and refill it.
        # Not on a shared budget, where a sibling dispatcher only looks for a
        # free slot every 50 ms: refilling at once took every slot until this
        # dispatcher's queue ran out, and the sibling got none.
        # The wait's 50 ms cap is how soon an abort flag or a sibling's released
        # slot is noticed, neither of which wakes it.
        $pkAnyFinished = ($pkStillRunning.Count -lt $pkRunning.Count)
        $pkRunning = $pkStillRunning

        if ($pkIsSharedBudget -or -not $pkAnyFinished) { Wait-PkRunningJobs -Jobs $pkRunning -CancelToken $pkCancelToken -TimeoutMs 50 }
    }
    } catch {
        # Best-effort teardown on the way out; the original error is rethrown.
        Stop-PkJobProcesses -Jobs $pkRunning
        foreach ($pkJob in $pkRunning) {
            try { if ($pkJob['Proc']) { $null = $pkJob['Proc'].WaitForExit(5000) } } catch { }
            if (-not $pkJob['SlotReleased']) {
                try { $null = & $pkJobAbortCleanup $pkJob } catch { }
                if ($pkIsSharedBudget) { try { $null = $pkMaxConcurrent.Release() } catch { } }
            }
            try { if ($pkJob['Proc']) { $pkJob['Proc'].Dispose() } } catch { }
        }
        throw
    }

    if ($pkCancelToken.IsCancellationRequested -and $pkRunning.Count -gt 0) {
        try {
            $pkAbortDeadline = [System.Diagnostics.Stopwatch]::StartNew()
            while ($pkRunning.Count -gt 0 -and -not [PkConsoleCtrl]::IsCloseEvent -and -not [PkConsoleCtrl]::SkipDrain -and $pkAbortDeadline.Elapsed.TotalSeconds -lt $pkAbortTimeoutSeconds) {
                # ---- BLOCK: graceful-wait loop ---- (keep in sync with the
                # main poll pass above and the final pass below)
                $pkStillWaiting = [System.Collections.Generic.List[hashtable]]::new()
                foreach ($pkJob in $pkRunning) {
                    if ($pkJob['TimeLimit'] -gt 0) { Stop-PkTimedOutJob -Job $pkJob }
                    if (& $pkJobPollCompleted $pkJob) {
                        $pkPendingBefore = $pkPending.Count
                        $null = & $pkJobFinalize $pkJob $pkPending
                        try { if ($pkJob['Proc']) { $pkJob['Proc'].Dispose() } } catch { }
                        if ($pkIsSharedBudget) { $null = $pkMaxConcurrent.Release() }
                        $pkJob['SlotReleased'] = $true
                        # Whatever JobFinalize queued (a retry, follow-up steps) is counted
                        # into its group HERE, by looking at the queue - not by trusting a
                        # returned flag. A flag with nothing queued would hang the group
                        # forever; two follow-ups would let it finish early.
                        # Only when the queue actually grew - walking it on every finished
                        # job would cost a full pass over a large batch each time.
                        if ($pkPending.Count -gt $pkPendingBefore) {
                            $pkQueuedIndex = 0
                            foreach ($pkQueued in $pkPending) {
                                if ($pkQueuedIndex -ge $pkPendingBefore) {
                                    if ($null -eq $pkQueued['GroupKey']) { $pkQueued['GroupKey'] = $pkJob['GroupKey']; if (-not $pkQueued.ContainsKey('Group')) { $pkQueued['Group'] = $pkJob['Group'] } }
                                    if ($pkGroupStates.ContainsKey($pkQueued['GroupKey'])) { $pkGroupStates[$pkQueued['GroupKey']].Outstanding++ }
                                }
                                $pkQueuedIndex++
                            }
                        }
                        if ($null -ne $pkJob['GroupKey']) {
                            $pkKey = $pkJob['GroupKey']
                            if ($pkGroupStates.ContainsKey($pkKey)) {
                                $pkState = $pkGroupStates[$pkKey]
                                $pkState.Outstanding--
                                if ($pkState.Outstanding -le 0 -and -not $pkState.Completed) {
                                    $null = & $pkGroupCompleteCallback $pkState.GroupInfo
                                    $pkState.Completed = $true
                                    $pkActiveGroupCount--
                                    $pkGroupResults.Add([pscustomobject][ordered]@{ GroupInfo = $pkState.GroupInfo; Completed = $true; Aborted = $false })
                                }
                            } else {
                                Write-PkMessage ("ProcessDispatch: invariant violation - job's GroupKey is not registered (graceful-wait loop). This should be unreachable.") -Level Error
                            }
                        }
                    } else {
                        $pkStillWaiting.Add($pkJob)
                    }
                }
                $pkRunning = $pkStillWaiting
                if ($pkRunning.Count -gt 0) { [System.Threading.Thread]::Sleep(250) }
            }

            # ---- BLOCK: mandatory final completion-check pass ----
            # A window-close can exit the loop above before a single poll, and
            # a job can finish in the last 250ms before the deadline. One more
            # pass so a finished job is never thrown away as "force-stopped".
            # (keep in sync with the two blocks above, except the time limit:
            # whatever is still running is force-stopped together just below)
            if ($pkRunning.Count -gt 0) {
                $pkStillWaiting = [System.Collections.Generic.List[hashtable]]::new()
                foreach ($pkJob in $pkRunning) {
                    if (& $pkJobPollCompleted $pkJob) {
                        $pkPendingBefore = $pkPending.Count
                        $null = & $pkJobFinalize $pkJob $pkPending
                        try { if ($pkJob['Proc']) { $pkJob['Proc'].Dispose() } } catch { }
                        if ($pkIsSharedBudget) { $null = $pkMaxConcurrent.Release() }
                        $pkJob['SlotReleased'] = $true
                        # Whatever JobFinalize queued (a retry, follow-up steps) is counted
                        # into its group HERE, by looking at the queue - not by trusting a
                        # returned flag. A flag with nothing queued would hang the group
                        # forever; two follow-ups would let it finish early.
                        # Only when the queue actually grew - walking it on every finished
                        # job would cost a full pass over a large batch each time.
                        if ($pkPending.Count -gt $pkPendingBefore) {
                            $pkQueuedIndex = 0
                            foreach ($pkQueued in $pkPending) {
                                if ($pkQueuedIndex -ge $pkPendingBefore) {
                                    if ($null -eq $pkQueued['GroupKey']) { $pkQueued['GroupKey'] = $pkJob['GroupKey']; if (-not $pkQueued.ContainsKey('Group')) { $pkQueued['Group'] = $pkJob['Group'] } }
                                    if ($pkGroupStates.ContainsKey($pkQueued['GroupKey'])) { $pkGroupStates[$pkQueued['GroupKey']].Outstanding++ }
                                }
                                $pkQueuedIndex++
                            }
                        }
                        if ($null -ne $pkJob['GroupKey']) {
                            $pkKey = $pkJob['GroupKey']
                            if ($pkGroupStates.ContainsKey($pkKey)) {
                                $pkState = $pkGroupStates[$pkKey]
                                $pkState.Outstanding--
                                if ($pkState.Outstanding -le 0 -and -not $pkState.Completed) {
                                    $null = & $pkGroupCompleteCallback $pkState.GroupInfo
                                    $pkState.Completed = $true
                                    $pkActiveGroupCount--
                                    $pkGroupResults.Add([pscustomobject][ordered]@{ GroupInfo = $pkState.GroupInfo; Completed = $true; Aborted = $false })
                                }
                            } else {
                                Write-PkMessage ("ProcessDispatch: invariant violation - job's GroupKey is not registered (final pass). This should be unreachable.") -Level Error
                            }
                        }
                    } else {
                        $pkStillWaiting.Add($pkJob)
                    }
                }
                $pkRunning = $pkStillWaiting
            }

            if ($pkRunning.Count -gt 0) {
                $pkDispatchResult.ForceKilledCount = $pkRunning.Count
                Write-PkMessage ("ProcessDispatch: force-stopping " + $pkRunning.Count + " job(s)" + (Get-PkForceStopReason -TimeoutSeconds $pkAbortTimeoutSeconds) + ".") -Level Warn
                Stop-PkJobProcesses -Jobs $pkRunning
                foreach ($pkJob in $pkRunning) {
                    try { if ($pkJob['Proc']) { $null = $pkJob['Proc'].WaitForExit(5000) } } catch { }
                    try { $null = & $pkJobAbortCleanup $pkJob } catch { }
                    try { if ($pkJob['Proc']) { $pkJob['Proc'].Dispose() } } catch { }
                    if ($pkIsSharedBudget) { try { $null = $pkMaxConcurrent.Release() } catch { } }
                    $pkJob['SlotReleased'] = $true
                }
            }
        } catch {
            Stop-PkJobProcesses -Jobs $pkRunning
            foreach ($pkJob in $pkRunning) {
                try { if ($pkJob['Proc']) { $null = $pkJob['Proc'].WaitForExit(5000) } } catch { }
                if (-not $pkJob['SlotReleased']) {
                    try { $null = & $pkJobAbortCleanup $pkJob } catch { }
                    if ($pkIsSharedBudget) { try { $null = $pkMaxConcurrent.Release() } catch { } }
                }
                try { if ($pkJob['Proc']) { $pkJob['Proc'].Dispose() } } catch { }
            }
            throw
        }
    }

    # Jobs still pending here were never started (only reachable via
    # cancellation). Clean them up and count them off, or their group could
    # never be reported.
    if ($pkPending.Count -gt 0) {
        foreach ($pkJob in $pkPending) {
            try { $null = & $pkJobAbortCleanup $pkJob } catch { }
            $pkKey = $pkJob['GroupKey']
            if ($pkGroupStates.ContainsKey($pkKey)) { $pkGroupStates[$pkKey].Outstanding-- }
        }
        $pkPending.Clear()
    }

    $pkDispatchResult.Aborted = $pkCancelToken.IsCancellationRequested
    foreach ($pkState in $pkGroupStates.Values) {
        if (-not $pkState.Completed) {
            # An aborted group still gets its callback - it's the only place
            # the caller can credit the jobs that DID finish before the stop.
            # Swallowed: one callback failing during teardown shouldn't cost
            # every other group its result.
            try { $null = & $pkGroupCompleteCallback $pkState.GroupInfo } catch { }
            $pkState.Completed = $true
            $pkGroupResults.Add([pscustomobject][ordered]@{ GroupInfo = $pkState.GroupInfo; Completed = $false; Aborted = $true })
        }
    }

    return [pscustomobject]$pkDispatchResult
}

function New-PkBatchResult {
    # One Invoke-PkProcessBatch result, the same shape however the command
    # ended: ran (-Completed is Complete-PkProcess's object), couldn't start
    # (-StartError), or stopped by an abort (-Aborted).
    param(
        [hashtable]$Command,
        $Completed = $null,
        [string]$StartError = $null,
        [switch]$Aborted,
        [bool]$TimedOut = $false
    )
    $r = [ordered]@{ Command = $Command; ExitCode = $null; Stdout = $null; Stderr = $null; StreamTimedOut = $false; StreamError = $null
                     StartError = $null; Aborted = [bool]$Aborted; TimedOut = $TimedOut }
    if ($null -ne $Completed) {
        $r.ExitCode = $Completed.ExitCode; $r.Stdout = $Completed.Stdout; $r.Stderr = $Completed.Stderr
        $r.StreamTimedOut = $Completed.StreamTimedOut; $r.StreamError = $Completed.StreamError
    }
    if ($StartError) { $r.StartError = $StartError }
    return [pscustomobject]$r
}

function Get-PkStartFailureCause {
    # Why a command couldn't start, for telling repeats apart: Windows' own text
    # for the error code where there is one, because on 7 the exception's text
    # for one failure differs by working directory.
    param([Parameter(Mandatory)][System.Management.Automation.ErrorRecord]$StartError)
    for ($e = $StartError.Exception; $null -ne $e; $e = $e.InnerException) {
        if ($e -is [System.ComponentModel.Win32Exception]) {
            return [System.ComponentModel.Win32Exception]::new($e.NativeErrorCode).Message.TrimEnd('.')
        }
    }
    return [string]$StartError
}

function Invoke-PkProcessBatch {
    # .SYNOPSIS
    # Runs a list of external programs, a limited number at a time, and returns
    # each one's exit code and output.
    # .DESCRIPTION
    # Each command is a hashtable: @{ FilePath = ...; Arguments = ... } plus,
    # optionally, WorkingDirectory, OutputEncoding (overrides -OutputEncoding),
    # TimeoutSeconds (overrides -TimeoutSeconds) and any keys of your own, which
    # come back on the result's Command. Inside
    # Invoke-PkRun, Ctrl+C lets running programs finish (up to -AbortTimeoutSeconds)
    # and starts no new ones; a second Ctrl+C kills them straight away. Every
    # command is tried, and one that can't start gets a StartError on its result.
    # Repeats of the same failure for the same program are reported once, with a
    # count at the end.
    # .PARAMETER Commands
    # The command hashtables. $null or empty returns no results.
    # .PARAMETER MaxConcurrent
    # How many programs run at once (default 4). -MaxParallel also works.
    # .PARAMETER OnComplete
    # { param($command, $result) } run on the main thread as each program finishes.
    # Not called for one that couldn't start or was stopped by an abort.
    # .PARAMETER AbortTimeoutSeconds
    # How long an abort waits for running programs before killing them (default 60).
    # -DrainTimeoutSeconds also works.
    # .PARAMETER TimeoutSeconds
    # Kill a program still running after this long (default 0, no limit). Its
    # result has TimedOut = $true.
    # .PARAMETER OutputEncoding
    # How to decode every program's output: a name like 'utf-8', a code page number,
    # or a [System.Text.Encoding]. Default: the console's code page.
    # .OUTPUTS
    # An object with Results, Aborted and ForceKilledCount. Each result has Command,
    # ExitCode, Stdout, Stderr, StreamTimedOut, StreamError, StartError, Aborted and
    # TimedOut, in the order the programs finished.
    # .EXAMPLE
    # $commands = foreach ($f in Get-ChildItem *.png) { @{ FilePath = 'cjxl.exe'; Arguments = (ConvertTo-PkArgumentString @($f.FullName, "$($f.FullName).jxl")) } }
    # $batch = Invoke-PkRun { Invoke-PkProcessBatch -Commands $commands -MaxConcurrent 6 }
    # $batch.Results | Format-Table ExitCode, Aborted, TimedOut
    param(
        [Parameter(Mandatory)]
        [AllowNull()]
        [AllowEmptyCollection()]
        [hashtable[]]$Commands,
        [Alias('MaxParallel')]
        [int]$MaxConcurrent = 4,
        [scriptblock]$OnComplete = $null,
        [Alias('DrainTimeoutSeconds')]
        [int]$AbortTimeoutSeconds = 60,
        [double]$TimeoutSeconds = 0,
        $OutputEncoding = $null
    )
    # pk-prefixed, parameters included: inside a worker runspace the kit isn't
    # a module, so a callback without .GetNewClosure() sees this frame's
    # variables. Same in Add-PkDispatchGroupJobs, Invoke-PkProcessDispatch, Invoke-PkProcessDispatchCore.
    $pkCommands = $Commands
    $pkMaxConcurrent = $MaxConcurrent
    $pkOnComplete = $OnComplete
    $pkAbortTimeoutSeconds = $AbortTimeoutSeconds
    $pkTimeoutSeconds = $TimeoutSeconds
    $pkOutputEncoding = $OutputEncoding
    Remove-Variable -Name Commands, MaxConcurrent, OnComplete, AbortTimeoutSeconds, TimeoutSeconds, OutputEncoding -Scope Local

    # Checked once here, so a bad name fails the call instead of every command.
    $null = Resolve-PkEncoding -Encoding $pkOutputEncoding
    # Invoke-PkProcessDispatch has the same check; this one names the batch.
    if ($pkMaxConcurrent -lt 1) { throw ("Invoke-PkProcessBatch: -MaxConcurrent must be at least 1 (got " + $pkMaxConcurrent + ").") }
    # Invoke-PkProcessDispatch has the same check; this one names the batch.
    if ($pkTimeoutSeconds -lt 0) { throw "Invoke-PkProcessBatch: -TimeoutSeconds must be 0 (no limit) or more." }

    $pkResults = [System.Collections.Generic.List[object]]::new()
    $pkState   = @{ Given = $false }
    # The closures below can't see the module's private functions (a
    # .GetNewClosure() block only sees global ones), so take these along.
    $pkNewBatchResult = ${function:New-PkBatchResult}
    $pkStartProcessCore = ${function:Start-PkProcessCore}
    $pkGetJobTimeLimit = ${function:Get-PkJobTimeLimit}
    $pkGetStartFailureCause = ${function:Get-PkStartFailureCause}
    $pkCallerState = $PSCmdlet.SessionState
    $pkStartFailures = [System.Collections.Specialized.OrderedDictionary]::new([System.StringComparer]::OrdinalIgnoreCase)

    # The first failure for a program and cause goes out in full; the rest only
    # add to the count that's reported after the dispatch.
    $pkReportStartFailure = {
        param($pkCommand, $pkError)
        $pkResults.Add((& $pkNewBatchResult -Command $pkCommand -StartError ([string]$pkError)))
        $pkFilePath = [string]$pkCommand['FilePath']
        $pkCause = & $pkGetStartFailureCause -StartError $pkError
        $pkFailureKey = $pkFilePath + '|' + $pkCause
        if ($pkStartFailures.Contains($pkFailureKey)) {
            $pkStartFailures[$pkFailureKey].More++
            return
        }
        $pkStartFailures[$pkFailureKey] = @{ FilePath = $pkFilePath; Cause = $pkCause; More = 0 }
        Write-PkMessage ("Invoke-PkProcessBatch: a command couldn't start: " + $pkError) -Level Error
    }.GetNewClosure()

    $pkGroupProvider = {
        if ($pkState.Given) { return $null }
        $pkState.Given = $true
        return @{ Name = 'batch' }
    }.GetNewClosure()

    $pkJobBuilder = {
        param($pkGroup)
        $pkJobs = [System.Collections.Generic.List[hashtable]]::new()
        foreach ($pkC in $pkCommands) {
            if ($null -eq $pkC) { continue }
            $pkEncoding = $pkOutputEncoding
            if ($pkC.ContainsKey('OutputEncoding')) { $pkEncoding = $pkC['OutputEncoding'] }
            # Here, not left to the dispatcher: a job it refuses never reaches the
            # starter below, so the command would get no result.
            try {
                $null = & $pkGetJobTimeLimit -Job $pkC
            } catch {
                & $pkReportStartFailure $pkC $_
                continue
            }
            $pkJobs.Add(@{ FilePath = $pkC['FilePath']; Arguments = $pkC['Arguments']; WorkingDirectory = [string]$pkC['WorkingDirectory']; OutputEncoding = $pkEncoding; TimeoutSeconds = $pkC['TimeoutSeconds']; Command = $pkC })
        }
        return $pkJobs
    }.GetNewClosure()

    $pkJobStarter = {
        param($pkJob)
        try {
            $pkStarted = & $pkStartProcessCore -CallerState $pkCallerState -FilePath $pkJob['FilePath'] -Arguments $pkJob['Arguments'] -WorkingDirectory $pkJob['WorkingDirectory'] -OutputEncoding $pkJob['OutputEncoding']
        } catch {
            $pkJob['StartFailureReported'] = $true
            & $pkReportStartFailure $pkJob['Command'] $_
            throw
        }
        $pkJob['Proc'] = $pkStarted.Proc; $pkJob['StdoutTask'] = $pkStarted.StdoutTask; $pkJob['StderrTask'] = $pkStarted.StderrTask
        $pkJob['Stopwatch'] = $pkStarted.Stopwatch
        return $pkJob
    }.GetNewClosure()

    $pkJobFinalize = {
        param($pkJob, $pkPendingQueue)
        $pkR = & $pkNewBatchResult -Command $pkJob['Command'] -Completed (Complete-PkProcess -Job $pkJob) -TimedOut ([bool]$pkJob['TimedOut'])
        $pkResults.Add($pkR)
        if ($null -ne $pkOnComplete) { $null = & $pkOnComplete $pkJob['Command'] $pkR }
        return @{ Success = ($pkR.ExitCode -eq 0) }
    }.GetNewClosure()

    $pkJobAbortCleanup = {
        param($pkJob)
        $pkResults.Add((& $pkNewBatchResult -Command $pkJob['Command'] -Aborted))
    }.GetNewClosure()

    $pkDispatchParams = @{
        GroupProvider = $pkGroupProvider; JobBuilder = $pkJobBuilder; JobStarter = $pkJobStarter
        JobFinalize = $pkJobFinalize; JobAbortCleanup = $pkJobAbortCleanup; MaxConcurrent = $pkMaxConcurrent
        AbortTimeoutSeconds = $pkAbortTimeoutSeconds; MaxQueueAhead = 1; TimeoutSeconds = $pkTimeoutSeconds
    }
    try {
        $pkDispatch = Invoke-PkProcessDispatch @pkDispatchParams
    } finally {
        foreach ($pkFailure in $pkStartFailures.Values) {
            if ($pkFailure.More -eq 0) { continue }
            $pkCommandWord = if ($pkFailure.More -eq 1) { 'command' } else { 'commands' }
            Write-PkMessage ("Invoke-PkProcessBatch: " + $pkFailure.More + " more " + $pkCommandWord + " couldn't start '" + $pkFailure.FilePath + "' (" + $pkFailure.Cause + ").") -Level Error
        }
    }

    return [pscustomobject][ordered]@{ Results = $pkResults; Aborted = $pkDispatch.Aborted; ForceKilledCount = $pkDispatch.ForceKilledCount }
}

# ==============================================================================
#  Runspace jobs - run PowerShell worker scripts in parallel
# ==============================================================================

function Get-PkWorkerSafeFunctionNames {
    # Kit functions every worker runspace gets automatically.
    return @('Write-PkMessage', 'Test-PkAbortSignal', 'Test-PkCancelRequested', 'Initialize-PkThreadPool', 'Stop-PkProcessTree', 'Stop-PkJobProcesses', 'Resolve-PkEncoding',
             'Start-PkProcess', 'Wait-PkProcess', 'Wait-PkRunningJobs', 'Complete-PkProcess', 'Invoke-PkProcessWithTimeout',
             'Invoke-PkProcessDispatch', 'Invoke-PkProcessDispatchCore', 'Invoke-PkProcessBatch',
             'Register-PkCancellationSource', 'Unregister-PkCancellationSource', 'New-PkBatchResult', 'ConvertTo-PkArgumentString', 'Get-PkForceStopReason', 'Resolve-PkFileSystemPath', 'Add-PkDispatchGroupJobs', 'Start-PkProcessCore', 'Get-PkJobTimeLimit', 'Stop-PkTimedOutJob', 'Get-PkStartFailureCause', 'Resolve-PkArguments')
}

function Get-PkHandlerParamCount {
    # How many parameters a callback declares, or -1 if it has no param()
    # block (it takes whatever it's given, in $args).
    param([Parameter(Mandatory)][scriptblock]$Callback)
    $ast = $Callback.Ast
    if ($ast -is [System.Management.Automation.Language.FunctionDefinitionAst]) {
        if ($null -ne $ast.Parameters) { return $ast.Parameters.Count }   # function f($a, $b)
        $ast = $ast.Body
    }
    if ($null -eq $ast.ParamBlock) { return -1 }
    return $ast.ParamBlock.Parameters.Count
}

function Add-PkCrashedJob {
    # A worker threw: count it, record it with its job on the run's outcome,
    # announce it, and tell -JobCrashedHandler. Shared by the main loop and
    # the abort drain. pk-prefixed parameters: when the kit was dot-sourced
    # rather than a module, a handler built without .GetNewClosure() saw them.
    param(
        [Parameter(Mandatory)][System.Collections.Specialized.OrderedDictionary]$PkOutcome,
        [hashtable]$PkJob,
        [Parameter(Mandatory)][System.Management.Automation.ErrorRecord]$PkError,
        [scriptblock]$PkHandler,
        [string]$PkWhen = ""
    )
    $PkOutcome.CrashedCount++
    $PkOutcome.Crashed.Add([pscustomobject][ordered]@{ Job = $PkJob; Error = $PkError })
    Invoke-PkMessageHandler -Level Error -Message ("Error collecting runspace result" + $PkWhen + ": " + $PkError)
    if ($null -eq $PkHandler) { return }
    try {
        # The job only goes to a handler that has room for it: a one-parameter
        # handler with [CmdletBinding()] or [Parameter()] would throw on a
        # second argument.
        $pkParamCount = Get-PkHandlerParamCount -Callback $PkHandler
        if ($pkParamCount -eq -1 -or $pkParamCount -ge 2) { $null = & $PkHandler $PkError $PkJob }
        else { $null = & $PkHandler $PkError }
    } catch {
        # Reported, not rethrown: a broken crash handler mustn't take the other workers down.
        Invoke-PkMessageHandler -Level Error -Message ("-JobCrashedHandler threw: " + $_)
    }
}

function Receive-PkCompletedHandles {
    param(
        [System.Collections.Generic.List[hashtable]]$Handles,
        [scriptblock]$ResultHandler,
        [System.Collections.Specialized.OrderedDictionary]$Outcome,
        [scriptblock]$JobCrashedHandler
    )
    $stillActive = [System.Collections.Generic.List[hashtable]]::new()
    foreach ($h in $Handles) {
        if ($h.Handle.IsCompleted) {
            # Not $results: when the kit was dot-sourced rather than a module, a
            # -ResultHandler built without .GetNewClosure() saw this function's
            # locals, and $results.Add($r) there grew the collection this loop
            # walks, so it never ended. Same in Invoke-PkRunspaceJobs.
            $pkWorkerOutput = $null
            try {
                $pkWorkerOutput = $h.PS.EndInvoke($h.Handle)
                # Same report as Invoke-PkRunspaceJobs' main loop.
                if ($h.PS.HadErrors) {
                    foreach ($e in $h.PS.Streams.Error) { Invoke-PkMessageHandler -Message ("Runspace error: " + $e.ToString()) -Level Error }
                }
            } catch {
                Add-PkCrashedJob -PkOutcome $Outcome -PkJob $h['Job'] -PkError $_ -PkHandler $JobCrashedHandler -PkWhen " during abort drain"
            } finally {
                $h.PS.Dispose()
            }
            if ($null -ne $ResultHandler -and $null -ne $pkWorkerOutput) {
                foreach ($r in $pkWorkerOutput) { $null = & $ResultHandler $r }
            }
        } else {
            $stillActive.Add($h)
        }
    }
    return ,$stillActive
}

function Invoke-PkGracefulDrain {
    # After an abort: give running workers $TimeoutSeconds to finish, collect
    # what they return, force-stop the rest. Leaves the native handler thread
    # parked: on a window close it's released when Invoke-PkRun ends, so the
    # rest of the run still gets the few seconds Windows allows.
    param(
        [Parameter(Mandatory)]
        [AllowEmptyCollection()]
        [System.Collections.Generic.List[hashtable]]$Handles,
        [scriptblock]$ResultHandler,
        [System.Collections.Concurrent.ConcurrentQueue[object]]$MessageQueue,
        [int]$TimeoutSeconds = 60,
        [string]$AbortWaitMessage,
        [Parameter(Mandatory)][System.Collections.Specialized.OrderedDictionary]$Outcome,
        [scriptblock]$JobCrashedHandler
    )

    if ($Handles.Count -eq 0) {
        return @{ ForceStoppedCount = 0 }
    }

    if (-not $PSBoundParameters.ContainsKey('AbortWaitMessage')) {
        $AbortWaitMessage = "[ABORT] Waiting for current jobs to finish (up to " + $TimeoutSeconds + "s)..."
    }

    $localHandles  = $Handles
    $abortDeadline = [System.Diagnostics.Stopwatch]::StartNew()
    $forceStoppedCount = 0

    if ($AbortWaitMessage -ne "") { Invoke-PkMessageHandler -Message $AbortWaitMessage -Level Warn }

    while ($localHandles.Count -gt 0 -and -not [PkConsoleCtrl]::IsCloseEvent -and -not [PkConsoleCtrl]::SkipDrain -and $abortDeadline.Elapsed.TotalSeconds -lt $TimeoutSeconds) {
        $localHandles = Receive-PkCompletedHandles -Handles $localHandles -ResultHandler $ResultHandler -Outcome $Outcome -JobCrashedHandler $JobCrashedHandler
        Receive-PkWorkerMessages -Queue $MessageQueue
        if ($localHandles.Count -gt 0) { [System.Threading.Thread]::Sleep(250) }
    }

    # One final pass before declaring anything force-stopped.
    if ($localHandles.Count -gt 0) {
        $localHandles = Receive-PkCompletedHandles -Handles $localHandles -ResultHandler $ResultHandler -Outcome $Outcome -JobCrashedHandler $JobCrashedHandler
        Receive-PkWorkerMessages -Queue $MessageQueue
    }

    if ($localHandles.Count -gt 0) {
        $forceStoppedCount = $localHandles.Count
        Invoke-PkMessageHandler -Level Error -Message ("[ABORT] Force-stopping " + $forceStoppedCount + " job(s)" + (Get-PkForceStopReason -TimeoutSeconds $TimeoutSeconds) + ".")
        foreach ($h in $localHandles) {
            # BeginStop, not Stop: Stop() blocks until the pipeline
            # actually unwinds, and a worker stuck in a .NET call never does.
            try { $null = $h.PS.BeginStop($null, $null) } catch { }
        }
    }

    Receive-PkWorkerMessages -Queue $MessageQueue

    return @{ ForceStoppedCount = $forceStoppedCount }
}

function Invoke-PkRunspaceJobs {
    # .SYNOPSIS
    # Runs a PowerShell scriptblock once per job, a limited number at a time, each in
    # its own runspace.
    # .DESCRIPTION
    # Each job hashtable's keys become the worker's parameters. A worker runspace
    # starts empty apart from cmdlets, installed modules and the kit's own worker
    # functions, so name every function of yours it calls in -SharedFunctionNames.
    # Each job starts in your current location, in a fresh scope: a folder change
    # or a variable from an earlier job doesn't carry over.
    # Only an error that stops the worker (throw, -ErrorAction Stop) counts as a
    # crash; a non-terminating one is printed and the job's output still counts.
    # The worker code is checked against the worker rules (see the README)
    # before anything starts, and each job's values before that job starts;
    # code or values that break them are refused.
    # .PARAMETER WorkerScript
    # A scriptblock with a param() block declaring every job key. If it declares
    # $CancelToken, it gets the run's cancellation token.
    # .PARAMETER JobParams
    # A list or array of job hashtables, or a single one. Use this or
    # -NextJobProvider.
    # .PARAMETER NextJobProvider
    # { } returning the next job hashtable, or $null when there are no more. Runs on
    # the main thread, so jobs can be produced lazily.
    # .PARAMETER SharedFunctionNames
    # Your functions the worker calls.
    # .PARAMETER MaxParallel
    # How many workers run at once. -MaxConcurrent also works.
    # .PARAMETER Cts
    # Your own CancellationTokenSource for the run; an abort cancels it too.
    # .PARAMETER ResultHandler
    # { param($result) } on the main thread, once per object a worker returns.
    # .PARAMETER PollCallback
    # { } on the main thread, every loop pass (for progress and the like).
    # .PARAMETER JobCrashedHandler
    # { param($errorRecord, $job) } on the main thread when a worker throws, also
    # during an abort's drain. $job is the job hashtable that crashed; leave it out
    # of param() if you don't need it. The worker's own error is
    # $errorRecord.Exception.InnerException. If the handler throws, that's reported
    # as a message and the run carries on.
    # .PARAMETER DrainTimeoutSeconds
    # How long an abort waits for running workers before force-stopping them
    # (default 60). -AbortTimeoutSeconds also works.
    # .PARAMETER AbortWaitMessage
    # The message shown while an abort waits; '' for none.
    # .PARAMETER CheckWorkerSafety
    # Check the worker code and job values before starting. On unless you pass
    # -CheckWorkerSafety:$false, whatever Get-Help says the default is.
    # .OUTPUTS
    # An object with ForceStoppedCount, CrashedCount, Aborted and Crashed (one
    # @{ Job; Error } entry per worker that threw).
    # .EXAMPLE
    # Invoke-PkRunspaceJobs -MaxParallel 4 -JobParams @(@{ Id = 1 }, @{ Id = 2 }) -WorkerScript { param($Id) $Id * 2 } -ResultHandler { param($r) Write-Host $r }
    param(
        [Parameter(Mandatory)]
        [scriptblock]$WorkerScript,
        $JobParams = $null,
        [scriptblock]$NextJobProvider = $null,
        [string[]]$SharedFunctionNames = @(),
        [Parameter(Mandatory)]
        [Alias('MaxConcurrent')]
        [int]$MaxParallel,
        [System.Threading.CancellationTokenSource]$Cts = $null,
        [scriptblock]$ResultHandler = $null,
        [scriptblock]$PollCallback = $null,
        [scriptblock]$JobCrashedHandler = $null,
        [Alias('AbortTimeoutSeconds')]
        [int]$DrainTimeoutSeconds = 60,
        [string]$AbortWaitMessage,
        # On unless turned off; see $checkSafety below.
        [switch]$CheckWorkerSafety
    )
    # A switch can't default to on without a lint warning, so "not passed"
    # means on. A bare -CheckWorkerSafety (the v1 opt-in) still means on.
    $checkSafety = (-not $PSBoundParameters.ContainsKey('CheckWorkerSafety')) -or $CheckWorkerSafety.IsPresent

    if ($null -eq $JobParams -and $null -eq $NextJobProvider) {
        throw "Invoke-PkRunspaceJobs: must supply either -JobParams or -NextJobProvider."
    }
    if ($null -ne $JobParams -and $null -ne $NextJobProvider) {
        throw "Invoke-PkRunspaceJobs: supply only one of -JobParams or -NextJobProvider, not both."
    }
    if ($MaxParallel -lt 1) { throw "Invoke-PkRunspaceJobs: -MaxParallel must be at least 1." }

    # Accept a List, an array, or a single hashtable. A job list built with
    # `foreach` collapses to ONE bare hashtable when there is only one job -
    # that must work the same as two.
    if ($null -ne $JobParams) {
        $normalizedJobs = [System.Collections.Generic.List[hashtable]]::new()
        if ($JobParams -is [hashtable]) {
            $normalizedJobs.Add($JobParams)
        } else {
            foreach ($jobEntry in $JobParams) {
                if ($jobEntry -isnot [hashtable]) {
                    throw ("Invoke-PkRunspaceJobs: -JobParams entry " + $normalizedJobs.Count + " is not a hashtable. Each job must be a hashtable of the worker's parameters.")
                }
                $normalizedJobs.Add($jobEntry)
            }
        }
        $JobParams = $normalizedJobs
    }

    $outcome = [ordered]@{ ForceStoppedCount = 0; CrashedCount = 0; Aborted = $false; Crashed = [System.Collections.Generic.List[object]]::new() }
    if ($null -ne $JobParams -and $JobParams.Count -eq 0) { return [pscustomobject]$outcome }

    if ($checkSafety) {
        $safetyFindings = Test-PkWorkerSafetyCore -WorkerScript $WorkerScript -SharedFunctionNames $SharedFunctionNames -SessionState $PSCmdlet.SessionState
        if ($safetyFindings.Count -gt 0) {
            $safetyLines = foreach ($f in $safetyFindings) { "  " + $f.Text }
            throw ("Invoke-PkRunspaceJobs: worker code breaks the worker-safety rules (see README.md):`r`n" + ($safetyLines -join "`r`n"))
        }
    }

    if ($null -eq $ResultHandler) { $ResultHandler = { param($r) } }

    # Which parameters the worker actually declares - passing one it doesn't
    # declare fails the whole invoke with an unhelpful binding error.
    $declaredParams = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
    if ($null -ne $WorkerScript.Ast.ParamBlock) {
        foreach ($p in $WorkerScript.Ast.ParamBlock.Parameters) { $null = $declaredParams.Add($p.Name.VariablePath.UserPath) }
    }

    # A fixed list can be checked before a single worker starts.
    if ($null -ne $JobParams) {
        for ($jobIndex = 0; $jobIndex -lt $JobParams.Count; $jobIndex++) {
            if ($null -eq $JobParams[$jobIndex]) { throw ("Invoke-PkRunspaceJobs: -JobParams entry " + $jobIndex + " is null.") }
            foreach ($key in $JobParams[$jobIndex].Keys) {
                if (-not $declaredParams.Contains([string]$key)) {
                    throw ("Invoke-PkRunspaceJobs: job " + $jobIndex + " supplies '" + $key + "', but -WorkerScript's param() block doesn't declare it. Nothing was started.")
                }
            }
            if ($checkSafety) {
                $sbKey = Get-PkScriptBlockJobKey -Job $JobParams[$jobIndex]
                if ($null -ne $sbKey) { throw ((Get-PkScriptBlockJobMessage -Job ("job " + $jobIndex) -Key $sbKey) + " Nothing was started.") }
            }
        }
    }

    $fixedListIndex = 0
    $ownCts         = $null
    $registeredCallerCts = $false
    $messageQueue   = $null
    $pool           = $null
    $handles        = [System.Collections.Generic.List[hashtable]]::new()
    $scanExhausted  = $false

    try {
        if ($null -eq $Cts) {
            $ownCts = [System.Threading.CancellationTokenSource]::new()
            Register-PkCancellationSource -Cts $ownCts
            $Cts = $ownCts
        } else {
            # The caller's own source: register it for the length of this
            # run so Ctrl+C cancels it too.
            Register-PkCancellationSource -Cts $Cts
            $registeredCallerCts = $true
        }
        $messageQueue = [System.Collections.Concurrent.ConcurrentQueue[object]]::new()

        $iss = [System.Management.Automation.Runspaces.InitialSessionState]::CreateDefault()
        $allShared = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
        foreach ($n in (Get-PkWorkerSafeFunctionNames)) { $null = $allShared.Add($n) }
        foreach ($n in $SharedFunctionNames)            { $null = $allShared.Add($n) }
        # The kit's worker functions come from this module; yours from where
        # you called this (a script's own functions, functions inside a
        # function, a module's private ones).
        $kitWorkerNames = [System.Collections.Generic.HashSet[string]]::new([string[]]@(Get-PkWorkerSafeFunctionNames), [System.StringComparer]::OrdinalIgnoreCase)
        $callerFns = Get-PkCallerFunction -SessionState $PSCmdlet.SessionState -Name @($allShared | Where-Object { -not $kitWorkerNames.Contains($_) })
        foreach ($sharedFn in $allShared) {
            $fnInfo = $null
            if ($kitWorkerNames.Contains($sharedFn)) { $fnInfo = Get-Item -LiteralPath ("Function:\" + $sharedFn) -ErrorAction SilentlyContinue }
            else { $fnInfo = $callerFns[$sharedFn] }
            if ($null -eq $fnInfo) {
                throw ("Invoke-PkRunspaceJobs: -SharedFunctionNames entry '" + $sharedFn + "' does not resolve to a defined function - check for a typo, or that the file defining it was dot-sourced before this call.")
            }
            $iss.Commands.Add([System.Management.Automation.Runspaces.SessionStateFunctionEntry]::new($sharedFn, $fnInfo.Definition))
        }
        # Global variables in every worker runspace: how kit functions know
        # they're in a worker, and where they find the run's token.
        $iss.Variables.Add([System.Management.Automation.Runspaces.SessionStateVariableEntry]::new('PkWorkerQueue', $messageQueue, 'ParallelKit worker message queue'))
        $iss.Variables.Add([System.Management.Automation.Runspaces.SessionStateVariableEntry]::new('PkCancelToken', $Cts.Token, 'ParallelKit run cancellation token'))

        $pool = [RunspaceFactory]::CreateRunspacePool(1, $MaxParallel, $iss, $Host)
        $pool.Open()

        # Each job starts in the caller's current location, the folder
        # Start-PkProcess defaults to as well. The real folder, not a drive
        # name: a New-PSDrive drive doesn't exist in the worker.
        $workerLocation = $ExecutionContext.SessionState.Path.CurrentFileSystemLocation.ProviderPath
        # Every job runs this: move to that folder, then run the worker in a
        # scope of its own with the job's values. Set per job because
        # runspaces are reused: a job that changed folder would otherwise move
        # the next one too. One script rather than a Set-Location statement
        # ahead of the worker: with a second statement, a pool runspace's
        # pipeline hadn't completed after 10 s in testing, on 5.1 and 7. The
        # prefix shares the worker's first line, so error line numbers still
        # match its code. If the folder is gone by the time a job starts, the
        # job runs wherever its runspace already is, without an error per job.
        $jobScript = 'param([string]$PkJobLocation, [hashtable]$PkJobValues) if ($PkJobLocation) { Set-Location -LiteralPath $PkJobLocation -ErrorAction SilentlyContinue }; & {' +
            $WorkerScript.ToString() + "`n} @PkJobValues"

        while ((-not $scanExhausted -or $handles.Count -gt 0) -and -not $Cts.Token.IsCancellationRequested) {

            while (-not $scanExhausted -and $handles.Count -lt $MaxParallel -and -not $Cts.Token.IsCancellationRequested) {
                if ($null -ne $JobParams) {
                    if ($fixedListIndex -lt $JobParams.Count) {
                        $nextJob = $JobParams[$fixedListIndex]
                        $fixedListIndex++
                    } else {
                        $nextJob = $null
                    }
                } else {
                    # Same as the dispatcher's builder: take the job
                    # hashtable, ignore anything else the provider let out.
                    $nextRaw = & $NextJobProvider
                    $nextJob = $null
                    $strayCount = 0
                    foreach ($rawItem in @($nextRaw)) {
                        if ($rawItem -is [hashtable]) { $nextJob = $rawItem } elseif ($null -ne $rawItem) { $strayCount++ }
                    }
                    if ($strayCount -gt 0) {
                        Invoke-PkMessageHandler -Level Warn -Message ("Invoke-PkRunspaceJobs: -NextJobProvider returned " + $strayCount + " value(s) that are not a job hashtable - ignored.")
                    }
                }
                if ($null -eq $nextJob) { $scanExhausted = $true; break }

                foreach ($key in $nextJob.Keys) {
                    if (-not $declaredParams.Contains([string]$key)) {
                        throw ("Invoke-PkRunspaceJobs: a job supplies '" + $key + "', but -WorkerScript's param() block doesn't declare it.")
                    }
                }
                if ($checkSafety -and $null -eq $JobParams) {
                    $sbKey = Get-PkScriptBlockJobKey -Job $nextJob
                    if ($null -ne $sbKey) { throw (Get-PkScriptBlockJobMessage -Job "a job from -NextJobProvider" -Key $sbKey) }
                }

                $ps = [PowerShell]::Create()
                $ps.RunspacePool = $pool
                $jobValues = @{}
                foreach ($key in $nextJob.Keys) { $jobValues[$key] = $nextJob[$key] }
                if ($declaredParams.Contains('CancelToken') -and -not $nextJob.ContainsKey('CancelToken')) {
                    $jobValues['CancelToken'] = $Cts.Token
                }
                $jobLocation = ""
                if ([System.IO.Directory]::Exists($workerLocation)) { $jobLocation = $workerLocation }
                # A local scope too, so variables a job sets (preference
                # variables included) don't carry over to the next job.
                $null = $ps.AddScript($jobScript, $true).AddParameter('PkJobLocation', $jobLocation).AddParameter('PkJobValues', $jobValues)
                $handles.Add(@{ PS = $ps; Handle = $ps.BeginInvoke(); Job = $nextJob })
            }

            $null = Test-PkAbortSignal
            Receive-PkWorkerMessages -Queue $messageQueue
            if ($null -ne $PollCallback) { $null = & $PollCallback }

            $stillPending = [System.Collections.Generic.List[hashtable]]::new()
            foreach ($h in $handles) {
                if ($h.Handle.IsCompleted) {
                    # Not $results: when the kit was dot-sourced rather than a
                    # module, a -ResultHandler or -JobCrashedHandler built without
                    # .GetNewClosure() saw this function's locals, and
                    # $results.Add($r) there grew the collection this loop
                    # walks, so it never ended. Same in Receive-PkCompletedHandles.
                    $pkWorkerOutput = $null
                    try {
                        $pkWorkerOutput = $h.PS.EndInvoke($h.Handle)
                        # Same report as Receive-PkCompletedHandles.
                        if ($h.PS.HadErrors) {
                            foreach ($e in $h.PS.Streams.Error) { Invoke-PkMessageHandler -Message ("Runspace error: " + $e.ToString()) -Level Error }
                        }
                    } catch {
                        # The worker itself threw - there is no result, so
                        # -ResultHandler is never called for this job.
                        Add-PkCrashedJob -PkOutcome $outcome -PkJob $h['Job'] -PkError $_ -PkHandler $JobCrashedHandler
                    } finally {
                        $h.PS.Dispose()
                    }
                    if ($null -ne $pkWorkerOutput) {
                        foreach ($r in $pkWorkerOutput) { $null = & $ResultHandler $r }
                    }
                } else {
                    $stillPending.Add($h)
                }
            }
            $handles = $stillPending
            if ($handles.Count -gt 0 -and ($scanExhausted -or $handles.Count -ge $MaxParallel)) {
                # Until a worker finishes or the token is cancelled. The 100 ms cap
                # keeps worker messages, -PollCallback and the abort flag moving.
                # WaitAny holds 63 handles at most on an STA thread, one of them the
                # token; a worker past that is only noticed when the time is up.
                $workerWaits = [System.Collections.Generic.List[System.Threading.WaitHandle]]::new()
                foreach ($h in $handles) {
                    if ($workerWaits.Count -ge 62) { break }
                    $workerWaits.Add($h.Handle.AsyncWaitHandle)
                }
                $workerWaits.Add($Cts.Token.WaitHandle)
                $null = [System.Threading.WaitHandle]::WaitAny($workerWaits.ToArray(), 100)
            }
        }

        if ($Cts.Token.IsCancellationRequested) {
            $drainArgs = @{ Handles = $handles; ResultHandler = $ResultHandler; MessageQueue = $messageQueue; TimeoutSeconds = $DrainTimeoutSeconds; Outcome = $outcome; JobCrashedHandler = $JobCrashedHandler }
            if ($PSBoundParameters.ContainsKey('AbortWaitMessage')) { $drainArgs.AbortWaitMessage = $AbortWaitMessage }
            $drainResult = Invoke-PkGracefulDrain @drainArgs
            $outcome.ForceStoppedCount = $drainResult.ForceStoppedCount
            $outcome.Aborted = $true
        }

        Receive-PkWorkerMessages -Queue $messageQueue
        if ($null -ne $PollCallback) { $null = & $PollCallback }
    } finally {
        # Best-effort teardown; whatever exception is already in flight is the one to surface.
        $stillRunning = $false
        foreach ($h in $handles) {
            try {
                if (-not $h.Handle.IsCompleted) { $stillRunning = $true; $null = $h.PS.BeginStop($null, $null) }
            } catch { }
        }
        if ($null -ne $pool) {
            # A worker stuck inside a .NET call can't be stopped, and
            # Dispose() would sit and wait for it. Close in the background
            # and move on; the abandoned worker ends when it returns or
            # the process exits.
            if ($stillRunning) {
                # An abandoned worker does NOT stop when its blocking call
                # returns - it can run on to its last line. Cancel the token
                # so a worker that checks Test-PkCancelRequested before an
                # irreversible step still gets told, even on a non-abort
                # exit (one of your callbacks threw).
                try { $Cts.Cancel() } catch { }
                try { $null = $pool.BeginClose($null, $null) } catch { }
            }
            else               { try { $pool.Dispose() } catch { } }
        }
        if ($null -ne $messageQueue) { try { Receive-PkWorkerMessages -Queue $messageQueue } catch { } }
        if ($null -ne $ownCts) {
            Unregister-PkCancellationSource -Cts $ownCts
            $ownCts.Dispose()
        }
        if ($registeredCallerCts) { Unregister-PkCancellationSource -Cts $Cts }
    }

    return [pscustomobject]$outcome
}

# ==============================================================================
#  Worker-safety check (see README.md, "The two rules")
# ==============================================================================

function Get-PkCallerFunction {
    # Looks function names up in the CALLER's session state, from the caller's
    # current scope: a script's own functions (.\script.ps1), functions
    # defined inside the calling function, a calling module's private ones.
    # Get-Item Function: here would search this module (plus global), and
    # SessionState.InvokeCommand.GetCommand only finds global functions.
    # An unbound scriptblock (made from text) run with InvokeScript(SessionState)
    # runs in that session state, dot-sourced into the caller's current scope.
    # So the work happens inside & { } and the names are embedded as quoted
    # literals: nothing is assigned in the caller's scope.
    # With -FollowAlias, an alias is followed to the function it points at.
    # Returns a hashtable: requested name -> FunctionInfo (missing = not found).
    param(
        [Parameter(Mandatory)][System.Management.Automation.SessionState]$SessionState,
        [string[]]$Name,
        [switch]$FollowAlias
    )
    $found = @{}
    $names = @($Name | Where-Object { -not [string]::IsNullOrEmpty($_) })
    if ($names.Count -eq 0) { return $found }
    $q = [string][char]39
    $quoted = foreach ($n in $names) { $q + [System.Management.Automation.Language.CodeGeneration]::EscapeSingleQuotedStringContent($n) + $q }
    $follow = '$false'
    if ($FollowAlias) { $follow = '$true' }
    $text = @'
& {
    foreach ($pkName in @(__NAMES__)) {
        $pkCmd = $pkName
        if (__FOLLOW__) {
            $pkHops = 0
            $pkAlias = Get-Item -LiteralPath ('Alias:' + $pkCmd) -ErrorAction SilentlyContinue
            while ($null -ne $pkAlias -and $pkHops -lt 5) {
                $pkCmd = $pkAlias.Definition
                $pkAlias = Get-Item -LiteralPath ('Alias:' + $pkCmd) -ErrorAction SilentlyContinue
                $pkHops++
            }
        }
        $pkFn = Get-Item -LiteralPath ('Function:' + $pkCmd) -ErrorAction SilentlyContinue
        if ($null -ne $pkFn) { [pscustomobject]@{ Name = $pkName; Fn = $pkFn } }
    }
}
'@
    $text = $text.Replace('__NAMES__', ($quoted -join ', ')).Replace('__FOLLOW__', $follow)
    $lookup = [scriptblock]::Create($text)
    foreach ($hit in $ExecutionContext.InvokeCommand.InvokeScript($SessionState, $lookup, @())) {
        $found[[string]$hit.Name] = $hit.Fn
    }
    return $found
}

function Get-PkCommandKind {
    # What a worker would need to run a command, given what the caller's
    # session resolves its name to ($Fn from Get-PkCallerFunction -FollowAlias,
    # or $null): 'Function' (one of your session's functions - must be
    # shared), 'UnloadableModuleFunction' (from a module a worker can't
    # autoload), or 'Other' (cmdlet, program, autoloadable module function,
    # or unknown). Works from the Alias: and Function: drives rather than
    # Get-Command: Get-Command on a name that doesn't resolve searches every
    # module on $env:PSModulePath, and the check runs on every
    # Invoke-PkRunspaceJobs call.
    param([System.Management.Automation.FunctionInfo]$Fn)
    if ($null -eq $Fn) { return 'Other' }
    if ([string]::IsNullOrEmpty($Fn.ModuleName)) { return 'Function' }
    # The kit's own: a worker gets only the worker-safe ones, so treat the
    # rest like a function of yours (needs listing), as before the kit was a module.
    if ($Fn.ModuleName -eq 'ParallelKit') { return 'Function' }
    # A module function (Get-FileHash, say) autoloads in a worker like a
    # cmdlet does - but only if the module can be found by name. One imported
    # by path from elsewhere can't.
    if ($null -ne (Get-Module -ListAvailable -Name $Fn.ModuleName -ErrorAction SilentlyContinue | Select-Object -First 1)) { return 'Other' }
    return 'UnloadableModuleFunction'
}

function Get-PkScriptBlockJobKey {
    # The first key of a job hashtable whose value is a scriptblock, or holds
    # one up to three levels down (in arrays, lists, dictionaries and
    # [pscustomobject]s), else $null. A scriptblock belongs to the runspace
    # that made it: run in a worker it executes against the main thread's
    # session state, which can corrupt it (the kit's own functions vanish
    # mid-run), crash, or hang.
    param([Parameter(Mandatory)][hashtable]$Job)
    foreach ($key in $Job.Keys) {
        if (Test-PkHoldsScriptBlock -Value $Job[$key] -Depth 3) { return [string]$key }
    }
    return $null
}

function Test-PkHoldsScriptBlock {
    # Get-PkScriptBlockJobKey's walk. Leaves (strings, numbers) are checked
    # inline rather than through a call, so a big object[] stays cheap, and
    # a collection whose element type can't hold anything (byte[], string[],
    # List[int]) isn't walked at all.
    param($Value, [int]$Depth)
    if ($null -eq $Value) { return $false }
    if ($Value -is [scriptblock]) { return $true }
    if ($Depth -le 0) { return $false }
    $type = $Value.GetType()
    if ($Value -is [System.Collections.IDictionary]) {
        $items = $Value.Values
    } elseif ($Value -is [System.Collections.IList]) {
        $items = $Value
    } elseif ($type.FullName -eq 'System.Management.Automation.PSCustomObject') {
        $items = foreach ($p in $Value.PSObject.Properties) { if ($p -is [System.Management.Automation.PSNoteProperty]) { $p.Value } }
    } else {
        return $false
    }
    $elementType = $null
    if ($type.IsArray) { $elementType = $type.GetElementType() }
    elseif ($type.IsGenericType) { $genericArgs = $type.GetGenericArguments(); $elementType = $genericArgs[$genericArgs.Length - 1] }
    if ($null -ne $elementType -and ($elementType.IsValueType -or $elementType -eq [string])) { return $false }
    try {
        foreach ($inner in $items) {
            if ($null -eq $inner -or $inner -is [string] -or $inner -is [System.ValueType]) { continue }
            if ($inner -is [scriptblock]) { return $true }
            if ($Depth -gt 1 -and (Test-PkHoldsScriptBlock -Value $inner -Depth ($Depth - 1))) { return $true }
        }
    } catch {
        # A collection other threads are changing (a results sink shared by
        # running workers) can't be enumerated safely; PowerShell may wrap
        # the "collection was modified" error, so catch it whatever its type.
        # Skip the value rather than fail the run: such sinks hold results,
        # not code.
        return $false
    }
    return $false
}

function Get-PkScriptBlockJobMessage {
    # Shared by the fixed-list and -NextJobProvider checks in Invoke-PkRunspaceJobs.
    param([string]$Job, [string]$Key)
    return ("Invoke-PkRunspaceJobs: " + $Job + " passes a scriptblock in '" + $Key + "'. A scriptblock made on the main thread and run in a worker can corrupt, crash or hang the run. " +
        "Pass its text instead (`$sb.ToString()) and rebuild it in the worker with [scriptblock]::Create(`$text), or pass -CheckWorkerSafety:`$false to skip this check.")
}

function Test-PkWorkerSafety {
    # .SYNOPSIS
    # Checks worker code against the worker rules without running it.
    # .DESCRIPTION
    # Invoke-PkRunspaceJobs runs this check itself; call it directly from your own
    # tests. Each finding has a Rule:
    #   MissingFunction  the worker calls a function of yours that isn't shared
    #   ScriptVariable   a shared function, or a nested block or function in the
    #                    worker, uses $script:
    #   DelegateCast     a scriptblock is cast to a .NET delegate, or passed into
    #                    a .NET method or constructor that turns it into one
    # Put "# pk:ignore" on a line to accept a finding there. Commands run through a
    # variable (& $cmd) aren't seen.
    # .PARAMETER WorkerScript
    # The worker scriptblock.
    # .PARAMETER SharedFunctionNames
    # The functions you'd pass to -SharedFunctionNames.
    # .OUTPUTS
    # A list of findings (empty when clean), each an object with Rule, Where, Line
    # and Text.

    # Scriptblocks handed to a worker as job values are refused separately,
    # by Invoke-PkRunspaceJobs (see Get-PkScriptBlockJobKey).
    param(
        [Parameter(Mandatory)]
        [scriptblock]$WorkerScript,
        [string[]]$SharedFunctionNames = @()
    )
    # Your functions are looked up where you called this from.
    return ,(Test-PkWorkerSafetyCore -WorkerScript $WorkerScript -SharedFunctionNames $SharedFunctionNames -SessionState $PSCmdlet.SessionState)
}

function Test-PkWorkerSafetyCore {
    # Test-PkWorkerSafety's body. -SessionState is the caller's, for finding
    # their functions (Invoke-PkRunspaceJobs passes its own caller's).
    param(
        [Parameter(Mandatory)][scriptblock]$WorkerScript,
        [string[]]$SharedFunctionNames = @(),
        [Parameter(Mandatory)][System.Management.Automation.SessionState]$SessionState
    )

    $findings = [System.Collections.Generic.List[object]]::new()
    $kitNames = [System.Collections.Generic.HashSet[string]]::new([string[]]@(Get-PkWorkerSafeFunctionNames), [System.StringComparer]::OrdinalIgnoreCase)
    $listed   = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
    foreach ($n in $kitNames)            { $null = $listed.Add($n) }
    foreach ($n in $SharedFunctionNames) { $null = $listed.Add($n) }

    # What to check: the worker body, plus every shared function of yours.
    $targets = [System.Collections.Generic.List[hashtable]]::new()
    $targets.Add(@{ Where = 'worker script'; Ast = $WorkerScript.Ast; IsWorkerBody = $true })
    $callerFns = Get-PkCallerFunction -SessionState $SessionState -Name @($SharedFunctionNames | Where-Object { -not $kitNames.Contains($_) })
    foreach ($n in $SharedFunctionNames) {
        if ($kitNames.Contains($n)) { continue }
        $fn = $callerFns[$n]
        if ($null -eq $fn) {
            $findings.Add([pscustomobject][ordered]@{ Rule = 'MissingFunction'; Where = '-SharedFunctionNames'; Line = 0; Text = ("-SharedFunctionNames lists '" + $n + "', which is not a defined function") })
            continue
        }
        $targets.Add(@{ Where = ("function " + $n); Ast = $fn.ScriptBlock.Ast; IsWorkerBody = $false })
    }

    # Every command name the code calls, resolved in the caller's session in
    # one lookup rather than one per name.
    $cmdNames = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
    foreach ($t in $targets) {
        foreach ($c in $t.Ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.CommandAst] }, $true)) {
            $cmdName = $c.GetCommandName()
            if ($cmdName) { $null = $cmdNames.Add($cmdName) }
        }
    }
    $resolvedFns = Get-PkCallerFunction -SessionState $SessionState -Name @($cmdNames) -FollowAlias
    $kindCache = @{}
    foreach ($t in $targets) {
        $ast = $t.Ast

        foreach ($c in $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.CommandAst] }, $true)) {
            $cmdName = $c.GetCommandName()
            if (-not $cmdName) { continue }
            if ($c.Extent.StartScriptPosition.Line -match '#\s*pk:ignore') { continue }
            if (-not $kindCache.ContainsKey($cmdName)) {
                $fnForKind = $resolvedFns[$cmdName]
                if ($null -eq $fnForKind) {
                    # One of the kit's private helpers: invisible to the caller,
                    # but a worker can't run it unless it's worker-safe either.
                    $ownFn = Get-Item -LiteralPath ('Function:' + $cmdName) -ErrorAction SilentlyContinue
                    if ($null -ne $ownFn -and $ownFn.ModuleName -eq 'ParallelKit') { $fnForKind = $ownFn }
                }
                $kindCache[$cmdName] = Get-PkCommandKind -Fn $fnForKind
            }
            $kind = $kindCache[$cmdName]
            if ($kind -eq 'Function' -and -not $listed.Contains($cmdName)) {
                $findings.Add([pscustomobject][ordered]@{ Rule = 'MissingFunction'; Where = $t.Where; Line = $c.Extent.StartLineNumber
                                 Text = ($t.Where + " (line " + $c.Extent.StartLineNumber + ") calls '" + $cmdName + "', which is not in -SharedFunctionNames") })
            } elseif ($kind -eq 'UnloadableModuleFunction' -and -not $listed.Contains($cmdName)) {
                $findings.Add([pscustomobject][ordered]@{ Rule = 'MissingFunction'; Where = $t.Where; Line = $c.Extent.StartLineNumber
                                 Text = ($t.Where + " (line " + $c.Extent.StartLineNumber + ") calls '" + $cmdName + "', from a module a worker can't load by name (imported by path?) - put the module on `$env:PSModulePath, or list the function in -SharedFunctionNames") })
            }
        }

        # $script: - anywhere in a shared function; only inside NESTED
        # scriptblocks of the worker body (its own top level is fine).
        $scriptVarScopes = [System.Collections.Generic.List[object]]::new()
        if ($t.IsWorkerBody) {
            foreach ($nested in $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.ScriptBlockExpressionAst] }, $true)) { $scriptVarScopes.Add($nested) }
            # A function defined inside the worker script is in the same
            # position as a shared one: called from a closure, its $script:
            # can read as empty.
            foreach ($innerFn in $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)) { $scriptVarScopes.Add($innerFn.Body) }
        } else {
            $scriptVarScopes.Add($ast)
        }
        $seenRefs = [System.Collections.Generic.HashSet[int]]::new()
        foreach ($scopeAst in $scriptVarScopes) {
            foreach ($ref in $scopeAst.FindAll({ param($node) $node -is [System.Management.Automation.Language.VariableExpressionAst] -and $node.VariablePath.IsScript }, $true)) {
                if (-not $seenRefs.Add($ref.Extent.StartOffset)) { continue }
                if ($ref.Extent.StartScriptPosition.Line -match '#\s*pk:ignore') { continue }
                $findings.Add([pscustomobject][ordered]@{ Rule = 'ScriptVariable'; Where = $t.Where; Line = $ref.Extent.StartLineNumber
                                 Text = ($t.Where + " (line " + $ref.Extent.StartLineNumber + ") uses `$" + $ref.VariablePath.UserPath + " - it can silently read as empty in a worker") })
            }
        }

        foreach ($cv in $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.ConvertExpressionAst] }, $true)) {
            if ($cv.Type.TypeName.Name -notmatch '^(System\.)?(Func|Action|Predicate|Comparison|Converter)(\[|`|$)') { continue }
            if ($cv.Extent.StartScriptPosition.Line -match '#\s*pk:ignore') { continue }
            $findings.Add([pscustomobject][ordered]@{ Rule = 'DelegateCast'; Where = $t.Where; Line = $cv.Extent.StartLineNumber
                             Text = ($t.Where + " (line " + $cv.Extent.StartLineNumber + ") casts a scriptblock to the delegate [" + $cv.Type.TypeName.Name + "] - this can hang or crash a worker") })
        }

        # The implicit form: a scriptblock literal passed as an argument to
        # a method or constructor - $dict.GetOrAdd($k, { ... }),
        # [System.Lazy[object]]::new({ ... }). No cast is written, but .NET
        # receives a delegate all the same. .ForEach()/.Where() are
        # PowerShell's own and take real scriptblocks, so they're fine.
        # The same goes for a variable assigned a scriptblock literal (or
        # { }.GetNewClosure()) anywhere in this code, then passed as
        # $lazy = [System.Lazy[object]]::new($factory). By name, not by flow:
        # a variable reassigned to something else in between is still flagged.
        # Methods that only store a value in a collection ($list.Add($sb),
        # $map.Add($k, $sb), $queue.Enqueue($sb)) aren't flagged: storing a
        # scriptblock makes no delegate. Not caught as a result: a collection
        # typed to hold delegates (List[Func[object]]), where .Add converts.
        $storageMethods = @('Add', 'AddRange', 'Insert', 'Enqueue', 'Push', 'TryAdd', 'Contains', 'Remove', 'IndexOf', 'set_Item')
        $scriptBlockVars = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
        foreach ($assign in $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.AssignmentStatementAst] }, $true)) {
            $target = $assign.Left
            if ($target -is [System.Management.Automation.Language.ConvertExpressionAst]) { $target = $target.Child }
            if ($target -isnot [System.Management.Automation.Language.VariableExpressionAst]) { continue }
            $rhs = $assign.Right
            if ($rhs -is [System.Management.Automation.Language.PipelineAst] -and $rhs.PipelineElements.Count -eq 1) { $rhs = $rhs.PipelineElements[0] }
            if ($rhs -is [System.Management.Automation.Language.CommandExpressionAst]) { $rhs = $rhs.Expression }
            if ($rhs -is [System.Management.Automation.Language.InvokeMemberExpressionAst] -and [string]$rhs.Member.Extent.Text -eq 'GetNewClosure') { $rhs = $rhs.Expression }
            if ($rhs -is [System.Management.Automation.Language.ScriptBlockExpressionAst]) { $null = $scriptBlockVars.Add($target.VariablePath.UserPath) }
        }
        foreach ($call in $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.InvokeMemberExpressionAst] }, $true)) {
            if ($null -eq $call.Arguments) { continue }
            $memberName = [string]$call.Member.Extent.Text
            if ($memberName -in @('ForEach', 'Where')) { continue }
            if ($memberName -in $storageMethods) { continue }
            $passed = $null
            foreach ($argument in $call.Arguments) {
                if ($argument -is [System.Management.Automation.Language.ScriptBlockExpressionAst]) { $passed = 'a scriptblock' }
                elseif ($argument -is [System.Management.Automation.Language.VariableExpressionAst] -and $scriptBlockVars.Contains($argument.VariablePath.UserPath)) {
                    $passed = ("the scriptblock in `$" + $argument.VariablePath.UserPath)
                }
            }
            if ($null -eq $passed) { continue }
            if ($call.Extent.StartScriptPosition.Line -match '#\s*pk:ignore') { continue }
            $findings.Add([pscustomobject][ordered]@{ Rule = 'DelegateCast'; Where = $t.Where; Line = $call.Extent.StartLineNumber
                             Text = ($t.Where + " (line " + $call.Extent.StartLineNumber + ") passes " + $passed + " to ." + $memberName + "() - .NET turns it into a delegate, which can hang or crash a worker (add '# pk:ignore' if this method really takes a scriptblock)") })
        }
    }

    return ,$findings
}

# ==============================================================================
#  Public functions (the ones README.md documents)
# ==============================================================================

# Imported globally (Import-Module -Global below): a .GetNewClosure() block
# can only see global functions, so this is what lets the batch's own
# callbacks, and yours, call them however your script was started.
# The same list is $publicFunctions in ParallelKit.Harness.ps1 (which checks
# each has Get-Help help and is visible); keep the two in step.
Export-ModuleMember -Function @(
    'Set-PkMessageHandler', 'Write-PkMessage', 'Initialize-ParallelKit', 'Register-PkCancellationSource',
    'Unregister-PkCancellationSource', 'Reset-PkAbortState', 'Request-PkAbort', 'Test-PkAbortSignal', 'Test-PkCancelRequested',
    'Get-PkAbortTriggerLabel', 'Invoke-PkRun', 'ConvertTo-PkArgumentString', 'Start-PkProcess', 'Stop-PkProcessTree',
    'Wait-PkProcess', 'Complete-PkProcess', 'Invoke-PkProcessWithTimeout', 'Invoke-PkProcessDispatch', 'Invoke-PkProcessBatch',
    'Invoke-PkRunspaceJobs', 'Test-PkWorkerSafety')

} | Import-Module -Global