winproc 0.1.0

data/ext/winproc/winproc.c

@@ -0,0 +1,1922 @@
+/*
+ * winproc — Windows process control for Ruby: argv-array spawning with exact
+ * quoting + per-handle inheritance, job objects with kill-on-close (crash-safe
+ * process trees), ConPTY pseudoconsoles, and UAC elevation helpers.
+ *
+ * PURE C (no C++), so rb_raise/longjmp is the normal, safe error mechanism —
+ * the same discipline as winipc/winloop/phylax, and the opposite of the lithos
+ * /EHsc hazard. Every kernel object lives in a TypedData wrapper whose free
+ * hook closes it, so a forgotten #close never leaks a HANDLE. Blocking waits
+ * release the GVL (rb_thread_call_without_gvl) with an unblock function so other
+ * Ruby threads run and Thread#kill / Ctrl-C / Timeout can break them.
+ *
+ * Include <ruby.h> before the Windows headers; never name a variable IN/OUT.
+ *
+ * Arch-neutral by construction: gates on _WIN64 (not _M_X64) and uses ULONG_PTR
+ * for handle-sized values; no inline asm. Builds unchanged on arm64-mswin.
+ *
+ * Links kernel32 (process/job/pipe/pseudoconsole, default) + advapi32
+ * (token/privilege/SID) + shell32 (ShellExecuteExW) + ole32 (CoInitializeEx).
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+#include <ruby/io.h>
+#include <limits.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <shellapi.h>   /* ShellExecuteExW, SHELLEXECUTEINFOW */
+#include <objbase.h>    /* CoInitializeEx / CoUninitialize */
+
+/* The mswin build compiles with _WIN32_WINNT = _WIN32_WINNT_WIN8 (0x0602), so
+ * these Windows 10+ ProcThreadAttribute selectors may be gated out of the SDK
+ * headers. Define them from their documented values (verified against
+ * <processthreadsapi.h>: ProcThreadAttributeValue(num, thread, input, additive))
+ * so the source builds regardless of the target-version macro. Behaviour at
+ * runtime is unchanged — the JOB_LIST attribute is Win10+, and PSEUDOCONSOLE is
+ * only ever used after the runtime CreatePseudoConsole probe (Win10 1809+). */
+#ifndef PROC_THREAD_ATTRIBUTE_JOB_LIST
+#  define PROC_THREAD_ATTRIBUTE_JOB_LIST \
+       ProcThreadAttributeValue(ProcThreadAttributeJobList, FALSE, TRUE, FALSE)
+#endif
+#ifndef PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE
+#  define PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE \
+       ProcThreadAttributeValue(ProcThreadAttributePseudoConsole, FALSE, TRUE, FALSE)
+#endif
+/* The two enum members above may also be absent; supply their documented
+ * ordinals (ProcThreadAttributeJobList = 13, ProcThreadAttributePseudoConsole =
+ * 22) when the SDK enum doesn't define them. */
+#ifndef ProcThreadAttributeJobList
+#  define ProcThreadAttributeJobList 13
+#endif
+#ifndef ProcThreadAttributePseudoConsole
+#  define ProcThreadAttributePseudoConsole 22
+#endif
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mWinproc;
+static VALUE cProcess, cJob, cStream, cPTY;
+static VALUE eError, eOSError, eNotFound, eAccessDenied, eCanceled, eBrokenPipe,
+             eElevationRequired, ePrivilegeNotHeld, eUnsupported,
+             eModeError, eClosed;
+
+/* ConPTY entry points resolved at runtime (absent on Windows < 10 1809). */
+typedef HRESULT (WINAPI *PFN_CreatePseudoConsole)(COORD, HANDLE, HANDLE, DWORD, void **);
+typedef HRESULT (WINAPI *PFN_ResizePseudoConsole)(void *, COORD);
+typedef void    (WINAPI *PFN_ClosePseudoConsole)(void *);
+static PFN_CreatePseudoConsole p_CreatePseudoConsole;
+static PFN_ResizePseudoConsole p_ResizePseudoConsole;
+static PFN_ClosePseudoConsole  p_ClosePseudoConsole;
+
+/* The private completion-port key for a Job's IOCP, and the wake key used by
+ * #close / ubf to break an in-flight GetQueuedCompletionStatus. */
+#define JOB_KEY  ((ULONG_PTR)0x4A4F4200) /* 'JOB\0' */
+#define WAKE_KEY ((ULONG_PTR)0x57414B45) /* 'WAKE'  */
+
+/* ------------------------------------------------------------ small helpers */
+
+/* UTF-8 Ruby String -> freshly xmalloc'd NUL-terminated UTF-16. Caller xfrees.
+ * Used for paths/argv/cwd/verbs — text, never binary payloads. */
+static WCHAR *
+to_wide(VALUE str)
+{
+    int len, n;
+    WCHAR *w;
+    StringValue(str);
+    len = (int)RSTRING_LEN(str);
+    if (len == 0) {
+        w = (WCHAR *)xmalloc(sizeof(WCHAR));
+        w[0] = 0;
+        return w;
+    }
+    n = MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, NULL, 0);
+    if (n <= 0) rb_raise(eError, "winproc: invalid UTF-8 in string");
+    w = (WCHAR *)xmalloc(sizeof(WCHAR) * (n + 1));
+    MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, w, n);
+    w[n] = 0;
+    return w;
+}
+
+/* Like to_wide but for a String that may legitimately contain embedded NULs
+ * (the env block "K=V\0K=V\0"); converts the whole byte run and appends the
+ * final double-NUL terminator. Returns NULL only for an empty input. */
+static WCHAR *
+env_to_wide(VALUE str)
+{
+    int len, n;
+    WCHAR *w;
+    StringValue(str);
+    len = (int)RSTRING_LEN(str);
+    if (len == 0) return NULL;
+    n = MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, NULL, 0);
+    if (n <= 0) rb_raise(eError, "winproc: invalid UTF-8 in environment");
+    /* +1 for the extra terminating NUL that closes the block. */
+    w = (WCHAR *)xmalloc(sizeof(WCHAR) * (n + 1));
+    MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, w, n);
+    w[n] = 0;
+    return w;
+}
+
+/* Build + raise a winproc error carrying @code (the Win32 error). The code must
+ * be captured by the caller immediately after the failing syscall. */
+static void
+raise_code(VALUE klass, const char *api, DWORD code)
+{
+    VALUE exc, msg;
+    WCHAR *buf = NULL;
+    char detail[512];
+    DWORD n;
+
+    detail[0] = 0;
+    n = FormatMessageW(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM |
+                       FORMAT_MESSAGE_IGNORE_INSERTS, NULL, code,
+                       MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPWSTR)&buf, 0, NULL);
+    if (n && buf) {
+        while (n && (buf[n-1] == L'\r' || buf[n-1] == L'\n' || buf[n-1] == L'.')) buf[--n] = 0;
+        WideCharToMultiByte(CP_UTF8, 0, buf, -1, detail, (int)sizeof(detail), NULL, NULL);
+        detail[sizeof(detail) - 1] = 0;
+    }
+    /* Release the OS buffer BEFORE any Ruby allocation, so an OOM longjmp from
+     * rb_sprintf / rb_exc_new_str cannot leak it. */
+    if (buf) LocalFree(buf);
+
+    if (detail[0])
+        msg = rb_sprintf("%s: %s (error %lu)", api, detail, (unsigned long)code);
+    else
+        msg = rb_sprintf("%s failed (error %lu)", api, (unsigned long)code);
+    exc = rb_exc_new_str(klass, msg);
+    rb_iv_set(exc, "@code", ULONG2NUM(code));
+    rb_exc_raise(exc);
+}
+
+/* Pick the right subclass for a Win32 error and raise it. */
+static void
+raise_gle(const char *api, DWORD code)
+{
+    VALUE klass = eOSError;
+    switch (code) {
+        case ERROR_FILE_NOT_FOUND:                                /* 2    */
+        case ERROR_PATH_NOT_FOUND:     klass = eNotFound;    break;/* 3    */
+        case ERROR_ACCESS_DENIED:      klass = eAccessDenied;break;/* 5    */
+        case ERROR_OPERATION_ABORTED:                             /* 995  */
+        case ERROR_CANCELLED:          klass = eCanceled;    break;/* 1223 */
+        case ERROR_BROKEN_PIPE:                                   /* 109  */
+        case ERROR_NO_DATA:                                       /* 232  */
+        case ERROR_PIPE_NOT_CONNECTED: klass = eBrokenPipe;  break;/* 233  */
+        case ERROR_ELEVATION_REQUIRED: klass = eElevationRequired; break; /* 740 */
+        case ERROR_NOT_ALL_ASSIGNED:   klass = ePrivilegeNotHeld;  break; /* 1300 */
+        case ERROR_NOT_SUPPORTED:                                 /* 50   */
+        case ERROR_CALL_NOT_IMPLEMENTED:                          /* 120  */
+        case ERROR_PROC_NOT_FOUND:     klass = eUnsupported; break;/* 127  */
+        default: break;
+    }
+    raise_code(klass, api, code);
+}
+
+/* =====================================================================
+ * Winproc::Process — wraps the child's process HANDLE
+ * ===================================================================== */
+
+typedef struct {
+    HANDLE h;             /* process handle; INVALID_HANDLE_VALUE sentinel */
+    HANDLE cancel_event;  /* manual-reset; ubf + #close wake for #wait      */
+    DWORD  pid;
+    DWORD  exit_code;     /* memoized once reaped                           */
+    int    exited;        /* exit_code valid                                */
+    volatile LONG waiters;/* #wait calls inside the no-GVL wait (E-30)      */
+    volatile LONG closing;/* set by #close; woken waiters raise Closed      */
+    int    closed;
+} process_t;
+
+static void
+process_free(void *p)
+{
+    process_t *pr = (process_t *)p;
+    /* GC can never run while a wait is in flight — the waiting thread's stack
+     * references the object — so free never races a waiter. Never terminates. */
+    if (pr->h && pr->h != INVALID_HANDLE_VALUE) CloseHandle(pr->h);
+    if (pr->cancel_event) CloseHandle(pr->cancel_event);
+    xfree(pr);
+}
+
+static const rb_data_type_t process_type = {
+    "Winproc::Process", { 0, process_free, 0, }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+process_alloc(VALUE klass)
+{
+    process_t *pr;
+    VALUE obj = TypedData_Make_Struct(klass, process_t, &process_type, pr);
+    pr->h = INVALID_HANDLE_VALUE;
+    pr->cancel_event = NULL;
+    pr->pid = 0;
+    pr->exit_code = 0;
+    pr->exited = 0;
+    pr->waiters = 0;
+    pr->closing = 0;
+    pr->closed = 0;
+    return obj;
+}
+
+static process_t *
+process_get(VALUE self)
+{
+    process_t *pr;
+    TypedData_Get_Struct(self, process_t, &process_type, pr);
+    return pr;
+}
+
+static process_t *
+process_live(VALUE self)
+{
+    process_t *pr = process_get(self);
+    if (pr->closed) rb_raise(eClosed, "winproc: process is closed");
+    return pr;
+}
+
+/* user-facing Process.new is forbidden; alloc exists only for safe GC. */
+static VALUE
+process_initialize(int argc, VALUE *argv, VALUE self)
+{
+    (void)argc; (void)argv; (void)self;
+    rb_raise(eError, "winproc: processes are created by Winproc.spawn / "
+                     "Winproc.pty / Winproc.runas");
+    return self;
+}
+
+/* --- interruptible, GVL-released wait on {h, cancel_event} ----------------- */
+
+typedef struct {
+    process_t *pr;
+    DWORD  ms;          /* INFINITE or remaining slice */
+    DWORD  wait;
+    DWORD  exit_code;
+    DWORD  gle;
+    int    got_exit;    /* exit_code valid */
+    int    do_closed;   /* woke with closing set */
+} pwait_t;
+
+static void *
+pwait_fn(void *p)
+{
+    pwait_t *w = (pwait_t *)p;
+    HANDLE hs[2];
+    DWORD r;
+    hs[0] = w->pr->h;
+    hs[1] = w->pr->cancel_event;
+    r = WaitForMultipleObjects(2, hs, FALSE, w->ms);
+    w->wait = r;
+    if (r == WAIT_OBJECT_0) {
+        DWORD code = 0;
+        if (GetExitCodeProcess(w->pr->h, &code)) {
+            w->exit_code = code;
+            w->got_exit = 1;
+        } else {
+            w->gle = GetLastError();
+        }
+    } else if (r == WAIT_OBJECT_0 + 1) {
+        /* cancel_event signaled: closing (E-30) or ubf interrupt */
+        if (w->pr->closing) w->do_closed = 1;
+    } else if (r == WAIT_FAILED) {
+        w->gle = GetLastError();
+    }
+    return NULL;
+}
+
+static void
+pwait_ubf(void *p)
+{
+    pwait_t *w = (pwait_t *)p;
+    SetEvent(w->pr->cancel_event); /* manual-reset: all concurrent waiters wake */
+}
+
+/* The body of Process#_wait, run inside rb_ensure so the waiters count is
+ * decremented on EVERY exit — including a Thread#kill / Timeout longjmp out of
+ * rb_thread_check_ints (otherwise the count would leak and #close would spin
+ * forever / the VM would tear the thread down with the count still held). */
+typedef struct { process_t *pr; long long ms_in; } pwait_args;
+
+static VALUE
+process_wait_body(VALUE vargs)
+{
+    pwait_args *a = (pwait_args *)vargs;
+    process_t *pr = a->pr;
+    int infinite = (a->ms_in < 0);
+    ULONGLONG deadline = infinite ? 0 : GetTickCount64() + (ULONGLONG)a->ms_in;
+
+    for (;;) {
+        pwait_t w;
+        DWORD slice;
+        if (infinite) {
+            slice = INFINITE;
+        } else {
+            ULONGLONG now = GetTickCount64();
+            ULONGLONG left;
+            if (now >= deadline) return Qnil;
+            left = deadline - now;
+            /* Clamp the per-wait slice below INFINITE (0xFFFFFFFF): the deadline
+             * loop re-waits, so a clamped slice on a multi-day timeout is exact,
+             * and a slice of exactly INFINITE would wait forever (E-Slice). */
+            slice = (left >= (ULONGLONG)INFINITE) ? (INFINITE - 1) : (DWORD)left;
+        }
+        w.pr = pr; w.ms = slice; w.wait = WAIT_FAILED;
+        w.exit_code = 0; w.gle = 0; w.got_exit = 0; w.do_closed = 0;
+        rb_thread_call_without_gvl(pwait_fn, &w, pwait_ubf, &w);
+
+        if (w.got_exit) {
+            pr->exit_code = w.exit_code;
+            pr->exited = 1;
+            return ULONG2NUM(w.exit_code);
+        }
+        if (w.wait == WAIT_OBJECT_0 && !w.got_exit)
+            raise_gle("GetExitCodeProcess", w.gle);
+        if (w.do_closed)
+            /* E-30: #close woke us. Do NOT ResetEvent — leave the manual-reset
+             * event set so sibling waiters also drain. */
+            rb_raise(eClosed, "winproc: process is closed");
+        if (w.wait == WAIT_FAILED)
+            raise_gle("WaitForMultipleObjects", w.gle);
+        /* cancel_event without closing => a ubf interrupt. Reset (GVL held),
+         * service interrupts (may longjmp), recompute, re-wait. */
+        if (w.wait == WAIT_OBJECT_0 + 1) {
+            ResetEvent(pr->cancel_event);
+            rb_thread_check_ints();
+            if (pr->closing || pr->closed)
+                rb_raise(eClosed, "winproc: process is closed");
+        }
+        /* WAIT_TIMEOUT loops; the deadline check at the top returns nil. */
+    }
+}
+
+static VALUE
+process_wait_ensure(VALUE vpr)
+{
+    process_t *pr = (process_t *)vpr;
+    InterlockedDecrement(&pr->waiters);
+    return Qnil;
+}
+
+/* Process#_wait(ms) -> exit code Integer, or nil on timeout (-1 ms = INFINITE).
+ * Memoizes the exit code. Raises Closed if #close is in progress. */
+static VALUE
+process_do_wait(VALUE self, VALUE vms)
+{
+    process_t *pr = process_get(self);
+    pwait_args a;
+
+    if (pr->exited) return ULONG2NUM(pr->exit_code); /* memoized; works after close */
+    if (pr->closed) rb_raise(eClosed, "winproc: process is closed");
+
+    a.pr = pr;
+    a.ms_in = NUM2LL(vms); /* 64-bit: ms can exceed LONG_MAX on LLP64 (E-Slice) */
+    InterlockedIncrement(&pr->waiters); /* under the GVL, before the region */
+    return rb_ensure(process_wait_body, (VALUE)&a, process_wait_ensure, (VALUE)pr);
+}
+
+static VALUE
+process_pid(VALUE self)
+{
+    /* never raises; works after close */
+    return ULONG2NUM(process_get(self)->pid);
+}
+
+static VALUE
+process_alive_p(VALUE self)
+{
+    process_t *pr = process_live(self);
+    DWORD r;
+    if (pr->exited) return Qfalse;
+    r = WaitForSingleObject(pr->h, 0);
+    if (r == WAIT_OBJECT_0) {
+        DWORD code = 0;
+        if (GetExitCodeProcess(pr->h, &code)) { pr->exit_code = code; pr->exited = 1; }
+        return Qfalse;
+    }
+    if (r == WAIT_TIMEOUT) return Qtrue;
+    raise_gle("WaitForSingleObject", GetLastError());
+    return Qfalse; /* unreached */
+}
+
+static VALUE
+process_exitstatus(VALUE self)
+{
+    process_t *pr = process_get(self);
+    DWORD r;
+    if (pr->exited) return ULONG2NUM(pr->exit_code);
+    if (pr->closed) return Qnil; /* memoized value or nil after close */
+    /* Only read GetExitCodeProcess after WaitForSingleObject reports signaled,
+     * so 259 STILL_ACTIVE is never exposed as a real status (E-17). */
+    r = WaitForSingleObject(pr->h, 0);
+    if (r == WAIT_OBJECT_0) {
+        DWORD code = 0;
+        if (GetExitCodeProcess(pr->h, &code)) {
+            pr->exit_code = code; pr->exited = 1;
+            return ULONG2NUM(code);
+        }
+        raise_gle("GetExitCodeProcess", GetLastError());
+    }
+    if (r == WAIT_TIMEOUT) return Qnil; /* still running */
+    raise_gle("WaitForSingleObject", GetLastError());
+    return Qnil; /* unreached */
+}
+
+static VALUE
+process_kill(int argc, VALUE *argv, VALUE self)
+{
+    process_t *pr = process_live(self);
+    VALUE vcode;
+    UINT code = 1;
+    DWORD r;
+    rb_scan_args(argc, argv, "01", &vcode);
+    if (!NIL_P(vcode)) code = (UINT)NUM2UINT(vcode);
+
+    if (pr->exited) return self; /* no-op if already exited */
+    r = WaitForSingleObject(pr->h, 0);
+    if (r == WAIT_OBJECT_0) {
+        DWORD c = 0;
+        if (GetExitCodeProcess(pr->h, &c)) { pr->exit_code = c; pr->exited = 1; }
+        return self; /* already gone */
+    }
+    if (!TerminateProcess(pr->h, code)) {
+        DWORD gle = GetLastError();
+        /* lost the race with natural exit: treat "already gone" as success */
+        if (gle == ERROR_ACCESS_DENIED) {
+            if (WaitForSingleObject(pr->h, 0) == WAIT_OBJECT_0) return self;
+        }
+        raise_gle("TerminateProcess", gle);
+    }
+    return self;
+}
+
+/* Memoize the exit code if the process has exited (used by #close / PTY close,
+ * so exitstatus answers after the handle is gone). Best-effort; never raises. */
+static void
+process_memoize_exit(process_t *pr)
+{
+    if (!pr->exited && pr->h != INVALID_HANDLE_VALUE) {
+        if (WaitForSingleObject(pr->h, 0) == WAIT_OBJECT_0) {
+            DWORD code = 0;
+            if (GetExitCodeProcess(pr->h, &code)) { pr->exit_code = code; pr->exited = 1; }
+        }
+    }
+}
+
+/* E-30 close discipline: set closing, wake any in-flight waiter, spin (no-GVL)
+ * until waiters drain, THEN close the handles. */
+typedef struct { process_t *pr; } pclose_t;
+static void *
+pclose_spin_fn(void *p)
+{
+    process_t *pr = ((pclose_t *)p)->pr;
+    while (pr->waiters) {
+        SetEvent(pr->cancel_event); /* re-wake: cover a waiter not yet blocked */
+        SleepEx(1, FALSE);
+    }
+    return NULL;
+}
+
+static VALUE
+process_close(VALUE self)
+{
+    process_t *pr = process_get(self);
+    if (pr->closed) return Qnil;
+    pr->closing = 1;
+    if (pr->cancel_event) {
+        pclose_t c; c.pr = pr;
+        SetEvent(pr->cancel_event);
+        rb_thread_call_without_gvl(pclose_spin_fn, &c, NULL, NULL);
+    }
+    process_memoize_exit(pr);
+    if (pr->h != INVALID_HANDLE_VALUE) { CloseHandle(pr->h); pr->h = INVALID_HANDLE_VALUE; }
+    if (pr->cancel_event) { CloseHandle(pr->cancel_event); pr->cancel_event = NULL; }
+    pr->closed = 1;
+    return Qnil;
+}
+
+static VALUE process_closed_p(VALUE self) { return process_get(self)->closed ? Qtrue : Qfalse; }
+
+/* =====================================================================
+ * Winproc::Stream — one end of a redirection / ConPTY pipe (synchronous I/O)
+ * ===================================================================== */
+
+typedef struct {
+    HANDLE h;
+    int    writable;          /* direction; ModeError enforcement           */
+    volatile LONG inflight;   /* 1 while a no-GVL read/write is running     */
+    volatile LONG closing;    /* set by close; in-flight op raises Closed   */
+    HANDLE op_thread;         /* DUPLICATED thread handle of the in-flight op
+                                 (published/retired ONLY under the GVL)      */
+    int    closed;
+} stream_t;
+
+static void
+stream_free(void *p)
+{
+    stream_t *s = (stream_t *)p;
+    /* GC can never run while an op is in flight — the op thread's stack
+     * references the object. */
+    if (s->h && s->h != INVALID_HANDLE_VALUE) CloseHandle(s->h);
+    if (s->op_thread) CloseHandle(s->op_thread);
+    xfree(s);
+}
+
+static const rb_data_type_t stream_type = {
+    "Winproc::Stream", { 0, stream_free, 0, }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+stream_alloc(VALUE klass)
+{
+    stream_t *s;
+    VALUE obj = TypedData_Make_Struct(klass, stream_t, &stream_type, s);
+    s->h = INVALID_HANDLE_VALUE;
+    s->writable = 0;
+    s->inflight = 0;
+    s->closing = 0;
+    s->op_thread = NULL;
+    s->closed = 0;
+    return obj;
+}
+
+static stream_t *
+stream_get(VALUE self)
+{
+    stream_t *s;
+    TypedData_Get_Struct(self, stream_t, &stream_type, s);
+    return s;
+}
+
+static stream_t *
+stream_live(VALUE self)
+{
+    stream_t *s = stream_get(self);
+    if (s->closed || s->h == INVALID_HANDLE_VALUE)
+        rb_raise(eClosed, "winproc: stream is closed");
+    return s;
+}
+
+static VALUE
+stream_initialize(int argc, VALUE *argv, VALUE self)
+{
+    (void)argc; (void)argv; (void)self;
+    rb_raise(eError, "winproc: streams are created by Winproc.spawn / Winproc.pty");
+    return self;
+}
+
+/* read/write run with the GVL released around a SYNCHRONOUS ReadFile/WriteFile,
+ * cancelable via CancelSynchronousIo(op_thread). The buffer is a private malloc
+ * (no RSTRING_PTR across the no-GVL region — GC-compaction rule). */
+typedef struct {
+    stream_t *s;
+    char  *buf;
+    DWORD  cap;       /* read: capacity / write: total length */
+    DWORD  done;      /* bytes transferred this call          */
+    DWORD  gle;
+    BOOL   ok;
+    int    is_write;
+} sio_t;
+
+static void *
+sio_fn(void *p)
+{
+    sio_t *io = (sio_t *)p;
+    DWORD n = 0;
+    if (io->is_write) {
+        DWORD off = 0;
+        io->ok = TRUE;
+        while (off < io->cap) {
+            if (!WriteFile(io->s->h, io->buf + off, io->cap - off, &n, NULL)) {
+                io->ok = FALSE; io->gle = GetLastError(); break;
+            }
+            off += n;
+        }
+        io->done = off;
+    } else {
+        io->ok = ReadFile(io->s->h, io->buf, io->cap, &n, NULL);
+        if (!io->ok) io->gle = GetLastError();
+        io->done = n;
+    }
+    /* clear inflight INSIDE the no-GVL fn so #close can spin on it w/o the GVL */
+    InterlockedExchange(&io->s->inflight, 0);
+    return NULL;
+}
+
+static void
+sio_ubf(void *p)
+{
+    sio_t *io = (sio_t *)p;
+    /* op's own per-iteration duplicate; valid exactly while the op sits in
+     * ReadFile/WriteFile (the inflight window). May be invoked repeatedly. */
+    if (io->s->op_thread) CancelSynchronousIo(io->s->op_thread);
+}
+
+/* Stream#_read(maxlen) -> binary String, or nil at EOF. */
+static VALUE
+stream_read(VALUE self, VALUE vmax)
+{
+    stream_t *s = stream_live(self);
+    long max = NUM2LONG(vmax);
+    VALUE out;
+
+    if (s->writable) rb_raise(eModeError, "winproc: cannot read a write-only stream");
+    if (max < 1 || max > 0x7FFFFFFFL)
+        rb_raise(rb_eArgError, "winproc: read length must be 1..0x7FFFFFFF");
+
+    for (;;) {
+        sio_t io;
+        HANDLE dup = NULL;
+        char *buf;
+
+        if (s->closing) rb_raise(eClosed, "winproc: stream is closed");
+
+        /* publish op_thread (GVL held), malloc the private buffer */
+        if (!DuplicateHandle(GetCurrentProcess(), GetCurrentThread(),
+                             GetCurrentProcess(), &dup, 0, FALSE, DUPLICATE_SAME_ACCESS))
+            raise_gle("DuplicateHandle", GetLastError());
+        buf = (char *)malloc((size_t)max);
+        if (!buf) { CloseHandle(dup); rb_raise(rb_eNoMemError, "winproc: out of memory"); }
+
+        s->op_thread = dup;
+        InterlockedExchange(&s->inflight, 1);
+
+        io.s = s; io.buf = buf; io.cap = (DWORD)max; io.done = 0;
+        io.gle = 0; io.ok = FALSE; io.is_write = 0;
+        rb_thread_call_without_gvl(sio_fn, &io, sio_ubf, &io);
+
+        /* RETIRE resources before anything that can longjmp */
+        s->op_thread = NULL;
+        CloseHandle(dup);
+
+        if (io.ok) {
+            if (io.done == 0) { free(buf); rb_thread_check_ints(); continue; } /* E-27 */
+            out = rb_str_new(buf, (long)io.done);
+            free(buf);
+            rb_enc_associate(out, rb_ascii8bit_encoding());
+            return out;
+        }
+        /* failure */
+        {
+            DWORD gle = io.gle;
+            free(buf);
+            if (gle == ERROR_BROKEN_PIPE || gle == ERROR_PIPE_NOT_CONNECTED ||
+                gle == ERROR_NO_DATA || gle == ERROR_HANDLE_EOF)
+                return Qnil; /* clean EOF */
+            if (gle == ERROR_OPERATION_ABORTED) {
+                if (s->closing) rb_raise(eClosed, "winproc: stream is closed");
+                rb_thread_check_ints(); /* interrupt; may longjmp, else retry */
+                continue;
+            }
+            raise_gle("ReadFile", gle);
+        }
+    }
+}
+
+/* Stream#_write body + ensure: the private buffer is freed on EVERY exit,
+ * including a Thread#kill / Timeout longjmp out of rb_thread_check_ints. */
+typedef struct { stream_t *s; char *buf; DWORD total; } swrite_args;
+
+static VALUE
+stream_write_body(VALUE vargs)
+{
+    swrite_args *a = (swrite_args *)vargs;
+    stream_t *s = a->s;
+    for (;;) {
+        sio_t io;
+        HANDLE dup = NULL;
+
+        if (s->closing) rb_raise(eClosed, "winproc: stream is closed");
+        if (!DuplicateHandle(GetCurrentProcess(), GetCurrentThread(),
+                             GetCurrentProcess(), &dup, 0, FALSE, DUPLICATE_SAME_ACCESS))
+            raise_gle("DuplicateHandle", GetLastError());
+        s->op_thread = dup;
+        InterlockedExchange(&s->inflight, 1);
+
+        io.s = s; io.buf = a->buf; io.cap = a->total; io.done = 0;
+        io.gle = 0; io.ok = FALSE; io.is_write = 1;
+        rb_thread_call_without_gvl(sio_fn, &io, sio_ubf, &io);
+
+        s->op_thread = NULL;
+        CloseHandle(dup);
+
+        if (io.ok) return ULONG2NUM(io.done);
+        if (io.gle == ERROR_OPERATION_ABORTED) {
+            if (s->closing) rb_raise(eClosed, "winproc: stream is closed");
+            rb_thread_check_ints(); /* may longjmp; the ensure frees buf */
+            /* Note: a partial write before cancel is lost; retry writes the
+             * whole buffer again. Anonymous-pipe writes are not cancelled
+             * mid-stream in practice, so this is the documented residual (§11). */
+            continue;
+        }
+        if (io.gle == ERROR_BROKEN_PIPE || io.gle == ERROR_NO_DATA ||
+            io.gle == ERROR_PIPE_NOT_CONNECTED)
+            raise_code(eBrokenPipe, "WriteFile", io.gle);
+        raise_gle("WriteFile", io.gle);
+    }
+}
+
+static VALUE
+stream_write_ensure(VALUE vargs)
+{
+    free(((swrite_args *)vargs)->buf);
+    return Qnil;
+}
+
+/* Stream#_write(bytes) -> Integer bytes written (writes ALL bytes). */
+static VALUE
+stream_write(VALUE self, VALUE data)
+{
+    stream_t *s = stream_live(self);
+    swrite_args a;
+    long len;
+
+    if (!s->writable) rb_raise(eModeError, "winproc: cannot write a read-only stream");
+    StringValue(data);
+    len = RSTRING_LEN(data);
+    if ((unsigned long long)len > 0x7FFFFFFFull)
+        rb_raise(rb_eArgError, "winproc: data too large (> 2 GiB)");
+    if (len == 0) return INT2FIX(0);
+
+    /* Copy bytes into a private buffer BEFORE releasing the GVL (no RSTRING_PTR
+     * across the no-GVL region). */
+    a.s = s;
+    a.buf = (char *)malloc((size_t)len);
+    if (!a.buf) rb_raise(rb_eNoMemError, "winproc: out of memory");
+    memcpy(a.buf, RSTRING_PTR(data), (size_t)len);
+    a.total = (DWORD)len;
+
+    return rb_ensure(stream_write_body, (VALUE)&a, stream_write_ensure, (VALUE)&a);
+}
+
+/* Stream#close — cancel any in-flight op (it raises Closed), then close. */
+typedef struct { stream_t *s; HANDLE dup; } sclose_t;
+static void *
+sclose_spin_fn(void *p)
+{
+    sclose_t *c = (sclose_t *)p;
+    while (c->s->inflight) {
+        if (c->dup) CancelSynchronousIo(c->dup);
+        SleepEx(1, FALSE);
+    }
+    return NULL;
+}
+
+static VALUE
+stream_close(VALUE self)
+{
+    stream_t *s = stream_get(self);
+    if (s->closed) return Qnil;
+    s->closing = 1;
+    if (s->inflight) {
+        sclose_t c;
+        HANDLE dup = NULL;
+        /* Take our OWN duplicate of op_thread under the GVL: it can never
+         * observe a retired/recycled handle, and keeps the thread object alive
+         * for the cancel below (§4, E-12). */
+        if (s->op_thread)
+            DuplicateHandle(GetCurrentProcess(), s->op_thread,
+                            GetCurrentProcess(), &dup, 0, FALSE, DUPLICATE_SAME_ACCESS);
+        c.s = s; c.dup = dup;
+        rb_thread_call_without_gvl(sclose_spin_fn, &c, NULL, NULL);
+        if (dup) CloseHandle(dup);
+    }
+    if (s->h != INVALID_HANDLE_VALUE) { CloseHandle(s->h); s->h = INVALID_HANDLE_VALUE; }
+    s->closed = 1;
+    return Qnil;
+}
+
+static VALUE stream_closed_p(VALUE self) { return stream_get(self)->closed ? Qtrue : Qfalse; }
+static VALUE stream_writable_p(VALUE self) { return stream_get(self)->writable ? Qtrue : Qfalse; }
+
+/* =====================================================================
+ * Winproc::Job — anonymous job object + private IOCP
+ * ===================================================================== */
+
+typedef struct {
+    HANDLE job;
+    HANDLE iocp;          /* private completion port, associated at create  */
+    volatile LONG waiting;/* wait_empty in-flight guard / E-30 drain flag   */
+    volatile LONG closing;/* set by #close; woken waiter raises Closed      */
+    int    closed;
+} job_t;
+
+static void
+job_free(void *p)
+{
+    job_t *j = (job_t *)p;
+    /* Close the IOCP FIRST, then the job — closing the job last is what fires
+     * KILL_ON_JOB_CLOSE; this is the crash-safe tree reaper. */
+    if (j->iocp) CloseHandle(j->iocp);
+    if (j->job)  CloseHandle(j->job);
+    xfree(j);
+}
+
+static const rb_data_type_t job_type = {
+    "Winproc::Job", { 0, job_free, 0, }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+job_alloc(VALUE klass)
+{
+    job_t *j;
+    VALUE obj = TypedData_Make_Struct(klass, job_t, &job_type, j);
+    j->job = NULL;
+    j->iocp = NULL;
+    j->waiting = 0;
+    j->closing = 0;
+    j->closed = 0;
+    return obj;
+}
+
+static job_t *
+job_get(VALUE self)
+{
+    job_t *j;
+    TypedData_Get_Struct(self, job_t, &job_type, j);
+    return j;
+}
+
+static job_t *
+job_live(VALUE self)
+{
+    job_t *j = job_get(self);
+    if (j->closed || !j->job) rb_raise(eClosed, "winproc: job is closed");
+    return j;
+}
+
+/* Job._create(kill_on_close, memory, process_memory, cpu_percent,
+ *             active_processes, cpu_time_100ns) -> Job. nil = "unset". */
+static VALUE
+job_create(VALUE klass, VALUE v_kill, VALUE v_mem, VALUE v_pmem,
+           VALUE v_cpu, VALUE v_active, VALUE v_time)
+{
+    VALUE obj = job_alloc(cJob);
+    job_t *j = job_get(obj);
+    JOBOBJECT_ASSOCIATE_COMPLETION_PORT acp;
+    JOBOBJECT_EXTENDED_LIMIT_INFORMATION eli;
+    DWORD flags = 0;
+
+    j->job = CreateJobObjectW(NULL, NULL);
+    if (!j->job) raise_gle("CreateJobObject", GetLastError());
+
+    j->iocp = CreateIoCompletionPort(INVALID_HANDLE_VALUE, NULL, 0, 1);
+    if (!j->iocp) {
+        DWORD gle = GetLastError();
+        CloseHandle(j->job); j->job = NULL;
+        raise_gle("CreateIoCompletionPort", gle);
+    }
+
+    /* Associate the port while the job is provably inactive (E-14). */
+    memset(&acp, 0, sizeof(acp));
+    acp.CompletionKey = (PVOID)JOB_KEY;
+    acp.CompletionPort = j->iocp;
+    if (!SetInformationJobObject(j->job, JobObjectAssociateCompletionPortInformation,
+                                 &acp, sizeof(acp))) {
+        DWORD gle = GetLastError();
+        CloseHandle(j->iocp); j->iocp = NULL;
+        CloseHandle(j->job);  j->job = NULL;
+        raise_gle("SetInformationJobObject(port)", gle);
+    }
+
+    /* One extended-limit Set combining KILL_ON_CLOSE / memory / time / active. */
+    memset(&eli, 0, sizeof(eli));
+    if (RTEST(v_kill)) flags |= JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
+    if (!NIL_P(v_mem)) {
+        flags |= JOB_OBJECT_LIMIT_JOB_MEMORY;
+        eli.JobMemoryLimit = (SIZE_T)NUM2ULL(v_mem);
+    }
+    if (!NIL_P(v_pmem)) {
+        flags |= JOB_OBJECT_LIMIT_PROCESS_MEMORY;
+        eli.ProcessMemoryLimit = (SIZE_T)NUM2ULL(v_pmem);
+    }
+    if (!NIL_P(v_active)) {
+        flags |= JOB_OBJECT_LIMIT_ACTIVE_PROCESS;
+        eli.BasicLimitInformation.ActiveProcessLimit = NUM2ULONG(v_active);
+    }
+    if (!NIL_P(v_time)) {
+        flags |= JOB_OBJECT_LIMIT_JOB_TIME;
+        eli.BasicLimitInformation.PerJobUserTimeLimit.QuadPart = (LONGLONG)NUM2LL(v_time);
+    }
+    eli.BasicLimitInformation.LimitFlags = flags;
+    if (flags && !SetInformationJobObject(j->job, JobObjectExtendedLimitInformation,
+                                          &eli, sizeof(eli))) {
+        DWORD gle = GetLastError();
+        /* job handle already owned by the TypedData; close() will fire
+         * KILL_ON_JOB_CLOSE (no processes yet) — consistent object. */
+        raise_gle("SetInformationJobObject(limits)", gle);
+    }
+
+    /* CPU rate control is the LAST Set so a raise (RDP/DFSS error 50 -> the
+     * Unsupported mapping) leaves a consistent, usable object (E-16). */
+    if (!NIL_P(v_cpu)) {
+        JOBOBJECT_CPU_RATE_CONTROL_INFORMATION crc;
+        memset(&crc, 0, sizeof(crc));
+        crc.ControlFlags = JOB_OBJECT_CPU_RATE_CONTROL_ENABLE |
+                           JOB_OBJECT_CPU_RATE_CONTROL_HARD_CAP;
+        crc.CpuRate = (DWORD)(NUM2ULONG(v_cpu) * 100);
+        if (!SetInformationJobObject(j->job, JobObjectCpuRateControlInformation,
+                                     &crc, sizeof(crc)))
+            raise_gle("SetInformationJobObject(cpu)", GetLastError());
+    }
+    return obj;
+}
+
+static VALUE
+job_assign(VALUE self, VALUE vprocess)
+{
+    job_t *j = job_live(self);
+    process_t *pr;
+    if (!rb_typeddata_is_kind_of(vprocess, &process_type))
+        rb_raise(rb_eTypeError, "winproc: expected a Winproc::Process");
+    pr = process_get(vprocess);
+    if (pr->closed || pr->h == INVALID_HANDLE_VALUE)
+        rb_raise(eClosed, "winproc: process is closed");
+    if (!AssignProcessToJobObject(j->job, pr->h))
+        raise_gle("AssignProcessToJobObject", GetLastError());
+    return self;
+}
+
+static VALUE
+job_terminate(int argc, VALUE *argv, VALUE self)
+{
+    job_t *j = job_live(self);
+    VALUE vcode;
+    UINT code = 1;
+    rb_scan_args(argc, argv, "01", &vcode);
+    if (!NIL_P(vcode)) code = (UINT)NUM2UINT(vcode);
+    if (!TerminateJobObject(j->job, code))
+        raise_gle("TerminateJobObject", GetLastError());
+    return self;
+}
+
+static LONG
+job_active_count(job_t *j)
+{
+    JOBOBJECT_BASIC_ACCOUNTING_INFORMATION acct;
+    memset(&acct, 0, sizeof(acct));
+    if (!QueryInformationJobObject(j->job, JobObjectBasicAccountingInformation,
+                                   &acct, sizeof(acct), NULL))
+        raise_gle("QueryInformationJobObject", GetLastError());
+    return (LONG)acct.ActiveProcesses;
+}
+
+static VALUE
+job_active_processes(VALUE self)
+{
+    job_t *j = job_live(self);
+    return LONG2NUM(job_active_count(j));
+}
+
+/* --- interruptible, GVL-released wait on the job IOCP ---------------------- */
+
+typedef struct {
+    job_t *j;
+    DWORD  ms;
+    DWORD  msg;        /* lpNumberOfBytes (message id) */
+    ULONG_PTR key;
+    BOOL   ok;
+    DWORD  gle;
+    int    timed_out;
+} jwait_t;
+
+static void *
+jwait_fn(void *p)
+{
+    jwait_t *w = (jwait_t *)p;
+    LPOVERLAPPED ov = NULL;
+    w->msg = 0; w->key = 0; w->gle = 0; w->timed_out = 0;
+    w->ok = GetQueuedCompletionStatus(w->j->iocp, &w->msg, &w->key, &ov, w->ms);
+    if (!w->ok) {
+        w->gle = GetLastError();
+        if (w->gle == WAIT_TIMEOUT) w->timed_out = 1;
+    }
+    return NULL;
+}
+
+static void
+jwait_ubf(void *p)
+{
+    jwait_t *w = (jwait_t *)p;
+    PostQueuedCompletionStatus(w->j->iocp, 0, WAKE_KEY, NULL);
+}
+
+/* Body of Job#_wait_empty, run inside rb_ensure so the waiting guard is always
+ * cleared — including a Thread#kill / Timeout longjmp out of
+ * rb_thread_check_ints (otherwise #close would spin forever). */
+typedef struct { job_t *j; long long ms_in; } jwait_args;
+
+static VALUE
+job_wait_empty_body(VALUE vargs)
+{
+    jwait_args *a = (jwait_args *)vargs;
+    job_t *j = a->j;
+    int infinite = (a->ms_in < 0);
+    ULONGLONG deadline;
+
+    /* short-circuit: already empty (accounting probe) */
+    if (job_active_count(j) == 0) return Qtrue;
+    deadline = infinite ? 0 : GetTickCount64() + (ULONGLONG)a->ms_in;
+
+    for (;;) {
+        jwait_t w;
+        DWORD slice;
+        if (infinite) {
+            slice = INFINITE;
+        } else {
+            ULONGLONG now = GetTickCount64();
+            ULONGLONG left;
+            if (now >= deadline) return Qfalse;
+            left = deadline - now;
+            /* Clamp below INFINITE; the deadline loop re-waits (E-Slice). */
+            slice = (left >= (ULONGLONG)INFINITE) ? (INFINITE - 1) : (DWORD)left;
+        }
+        w.j = j; w.ms = slice;
+        rb_thread_call_without_gvl(jwait_fn, &w, jwait_ubf, &w);
+
+        if (w.ok) {
+            if (w.key == WAKE_KEY) {
+                if (j->closing) rb_raise(eClosed, "winproc: job is closed");
+                rb_thread_check_ints(); /* ubf interrupt; may longjmp */
+                if (j->closing || j->closed || !j->iocp)
+                    rb_raise(eClosed, "winproc: job is closed");
+                continue;
+            }
+            if (w.key == JOB_KEY && w.msg == JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO) {
+                /* re-verify accounting (stale-message guard, E-15) */
+                if (job_active_count(j) == 0) return Qtrue;
+            }
+            /* other messages ignored */
+            continue;
+        }
+        if (w.timed_out) {
+            if (infinite) continue; /* spurious */
+            { ULONGLONG now = GetTickCount64();
+              if (now >= deadline) return Qfalse; }
+            continue;
+        }
+        raise_gle("GetQueuedCompletionStatus", w.gle);
+    }
+}
+
+static VALUE
+job_wait_empty_ensure(VALUE vj)
+{
+    job_t *j = (job_t *)vj;
+    InterlockedExchange(&j->waiting, 0);
+    return Qnil;
+}
+
+/* Job#_wait_empty(ms) -> true (empty) | false (timeout). */
+static VALUE
+job_wait_empty(VALUE self, VALUE vms)
+{
+    job_t *j = job_get(self);
+    jwait_args a;
+
+    if (j->closed || !j->job) rb_raise(eClosed, "winproc: job is closed");
+
+    /* Convert the timeout BEFORE claiming the in-flight guard: a raise here
+     * (e.g. a non-numeric ms) must not leave waiting==1 stuck — that would wedge
+     * job_close's drain spin forever. NUM2LL is 64-bit so a multi-day ms never
+     * overflows on LLP64 (where long is 32-bit); the wait loop clamps each slice
+     * below INFINITE. (E-Slice / the close-wedge fix.) */
+    a.j = j;
+    a.ms_in = NUM2LL(vms);
+
+    if (InterlockedCompareExchange(&j->waiting, 1, 0) != 0)
+        rb_raise(eError, "winproc: another wait_empty is already in flight");
+
+    return rb_ensure(job_wait_empty_body, (VALUE)&a, job_wait_empty_ensure, (VALUE)j);
+}
+
+/* E-30 close: set closing, re-post WAKE until the waiter drains, then close
+ * IOCP then job (kill-on-close fires here). */
+typedef struct { job_t *j; } jclose_t;
+static void *
+jclose_spin_fn(void *p)
+{
+    job_t *j = ((jclose_t *)p)->j;
+    while (j->waiting) {
+        PostQueuedCompletionStatus(j->iocp, 0, WAKE_KEY, NULL);
+        SleepEx(1, FALSE);
+    }
+    return NULL;
+}
+
+static VALUE
+job_close(VALUE self)
+{
+    job_t *j = job_get(self);
+    if (j->closed) return Qnil;
+    j->closing = 1;
+    if (j->waiting && j->iocp) {
+        jclose_t c; c.j = j;
+        PostQueuedCompletionStatus(j->iocp, 0, WAKE_KEY, NULL);
+        rb_thread_call_without_gvl(jclose_spin_fn, &c, NULL, NULL);
+    }
+    if (j->iocp) { CloseHandle(j->iocp); j->iocp = NULL; }
+    if (j->job)  { CloseHandle(j->job);  j->job = NULL; } /* kill-on-close fires */
+    j->closed = 1;
+    return Qnil;
+}
+
+static VALUE job_closed_p(VALUE self) { return job_get(self)->closed ? Qtrue : Qfalse; }
+
+/* =====================================================================
+ * Winproc::PTY — HPCON + (process/streams live as Ruby ivars)
+ * ===================================================================== */
+
+typedef struct {
+    void *hpc;            /* HPCON; NULL sentinel */
+    int   cols;
+    int   rows;
+    int   closed;
+} pty_t;
+
+static void
+pty_free(void *p)
+{
+    pty_t *t = (pty_t *)p;
+    /* NEVER ClosePseudoConsole here — deliberately LEAK the HPCON (and its
+     * conhost, until process exit). Sweep order is arbitrary, so the output
+     * Stream may still be open/undrained; pre-24H2 ClosePseudoConsole would then
+     * block INDEFINITELY inside GC with the GVL held. A bounded leak beats a
+     * GVL-held hang. README: always close PTYs explicitly. */
+    xfree(t);
+}
+
+static const rb_data_type_t pty_type = {
+    "Winproc::PTY", { 0, pty_free, 0, }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+pty_alloc(VALUE klass)
+{
+    pty_t *t;
+    VALUE obj = TypedData_Make_Struct(klass, pty_t, &pty_type, t);
+    t->hpc = NULL;
+    t->cols = 0;
+    t->rows = 0;
+    t->closed = 0;
+    return obj;
+}
+
+static pty_t *
+pty_get(VALUE self)
+{
+    pty_t *t;
+    TypedData_Get_Struct(self, pty_t, &pty_type, t);
+    return t;
+}
+
+static pty_t *
+pty_live(VALUE self)
+{
+    pty_t *t = pty_get(self);
+    if (t->closed || !t->hpc) rb_raise(eClosed, "winproc: pty is closed");
+    return t;
+}
+
+static VALUE
+pty_initialize(int argc, VALUE *argv, VALUE self)
+{
+    (void)argc; (void)argv; (void)self;
+    rb_raise(eError, "winproc: pseudoconsoles are created by Winproc.pty");
+    return self;
+}
+
+static VALUE
+pty_resize(VALUE self, VALUE vcols, VALUE vrows)
+{
+    pty_t *t = pty_live(self);
+    int cols = NUM2INT(vcols), rows = NUM2INT(vrows);
+    COORD size;
+    HRESULT hr;
+    if (cols < 1 || cols > 0x7FFF || rows < 1 || rows > 0x7FFF)
+        rb_raise(rb_eArgError, "winproc: cols/rows must be 1..32767");
+    size.X = (SHORT)cols; size.Y = (SHORT)rows;
+    hr = p_ResizePseudoConsole(t->hpc, size);
+    if (FAILED(hr)) raise_code(eOSError, "ResizePseudoConsole", (DWORD)(hr & 0xFFFF));
+    t->cols = cols; t->rows = rows;
+    return self;
+}
+
+static VALUE pty_cols(VALUE self) { return INT2NUM(pty_get(self)->cols); }
+static VALUE pty_rows(VALUE self) { return INT2NUM(pty_get(self)->rows); }
+
+/* PTY#_close_pty — no-GVL ClosePseudoConsole (the Ruby layer has already closed
+ * the output Stream, so this cannot deadlock; bounded, no cancel API). */
+typedef struct { void *hpc; } pclosepty_t;
+static void *
+pty_close_fn(void *p)
+{
+    p_ClosePseudoConsole(((pclosepty_t *)p)->hpc);
+    return NULL;
+}
+
+static VALUE
+pty_close_pty(VALUE self)
+{
+    pty_t *t = pty_get(self);
+    if (t->closed || !t->hpc) { t->closed = 1; return Qnil; }
+    {
+        pclosepty_t c; c.hpc = t->hpc;
+        rb_thread_call_without_gvl(pty_close_fn, &c, NULL, NULL);
+    }
+    t->hpc = NULL;
+    t->closed = 1;
+    return Qnil;
+}
+
+static VALUE pty_closed_p(VALUE self) { return pty_get(self)->closed ? Qtrue : Qfalse; }
+
+/* =====================================================================
+ * Winproc._spawn — the one CreateProcessW path (redirected & ConPTY modes)
+ * ===================================================================== */
+
+/* stdio slot kinds, kept in sync with the Ruby layer's encoding. */
+enum { SLOT_INHERIT = 0, SLOT_NULL = 1, SLOT_PIPE = 2, SLOT_IO = 3, SLOT_MERGE = 4 };
+
+/* Everything acquired by _spawn lives here so a single fail: path cleans up. */
+typedef struct {
+    /* inputs (borrowed; freed on both paths) */
+    WCHAR *app;
+    WCHAR *cmdline;   /* writable copy (CreateProcessW may modify) */
+    WCHAR *cwd;
+    WCHAR *envblock;
+
+    /* attribute list */
+    LPPROC_THREAD_ATTRIBUTE_LIST attr;
+    SIZE_T attr_size;
+    int attr_inited;
+
+    /* HANDLE_LIST (≤3, deduped) + job + hpcon — must outlive CreateProcess AND
+     * DeleteProcThreadAttributeList (E-4). */
+    HANDLE hlist[3];
+    DWORD  hcount;
+    HANDLE hjob;
+    void  *hpcon;
+
+    /* per-slot child handles we created (to close after CreateProcess) */
+    HANDLE child_in, child_out, child_err;
+    /* parent ends to hand to Stream objects */
+    HANDLE par_in_w, par_out_r, par_err_r;
+    /* PTY: our pipe ends + pty-side ends */
+    HANDLE pty_in_w, pty_out_r, pty_in_r, pty_out_w;
+
+    PROCESS_INFORMATION pi;
+    int created;          /* CreateProcessW succeeded */
+
+    /* pre-allocated Ruby objects (E-31): nothing raise-able after CreateProcess */
+    VALUE proc_obj;
+    VALUE in_obj, out_obj, err_obj;  /* Streams for :pipe slots (redirected) */
+    VALUE pty_obj, pty_in_obj, pty_out_obj;
+    HANDLE cancel_event;
+} spawn_ctx;
+
+static void
+spawn_cleanup_partial(spawn_ctx *c)
+{
+    /* close created-but-unowned handles; called on the fail path */
+    if (c->attr_inited) DeleteProcThreadAttributeList(c->attr);
+    if (c->attr) free(c->attr);
+    if (c->child_in)  CloseHandle(c->child_in);
+    if (c->child_out) CloseHandle(c->child_out);
+    if (c->child_err && c->child_err != c->child_out) CloseHandle(c->child_err);
+    if (c->par_in_w)  CloseHandle(c->par_in_w);
+    if (c->par_out_r) CloseHandle(c->par_out_r);
+    if (c->par_err_r) CloseHandle(c->par_err_r);
+    if (c->pty_in_w)  CloseHandle(c->pty_in_w);
+    if (c->pty_out_r) CloseHandle(c->pty_out_r);
+    if (c->pty_in_r)  CloseHandle(c->pty_in_r);
+    if (c->pty_out_w) CloseHandle(c->pty_out_w);
+    if (c->hpcon && p_ClosePseudoConsole) p_ClosePseudoConsole(c->hpcon);
+    if (c->cancel_event) CloseHandle(c->cancel_event);
+    if (c->app)      xfree(c->app);
+    if (c->cmdline)  xfree(c->cmdline);
+    if (c->cwd)      xfree(c->cwd);
+    if (c->envblock) xfree(c->envblock);
+}
+
+/* Make an inheritable NUL handle (fallback for a parent without std handles). */
+static HANDLE
+open_nul_inheritable(void)
+{
+    SECURITY_ATTRIBUTES sa;
+    sa.nLength = sizeof(sa); sa.lpSecurityDescriptor = NULL; sa.bInheritHandle = TRUE;
+    return CreateFileW(L"NUL", GENERIC_READ | GENERIC_WRITE,
+                       FILE_SHARE_READ | FILE_SHARE_WRITE, &sa, OPEN_EXISTING, 0, NULL);
+}
+
+/* Duplicate a std handle as inheritable, falling back to NUL (E-7). std is one
+ * of STD_INPUT_HANDLE/STD_OUTPUT_HANDLE/STD_ERROR_HANDLE. */
+static HANDLE
+inherit_std_or_nul(DWORD std)
+{
+    HANDLE src = GetStdHandle(std);
+    HANDLE dup = NULL;
+    if (src == NULL || src == INVALID_HANDLE_VALUE)
+        return open_nul_inheritable();
+    if (DuplicateHandle(GetCurrentProcess(), src, GetCurrentProcess(), &dup,
+                        0, TRUE, DUPLICATE_SAME_ACCESS))
+        return dup;
+    return open_nul_inheritable();
+}
+
+/* Build one redirected stdio slot. spec_kind is SLOT_*; for SLOT_IO, vio is the
+ * Ruby IO. Sets *child (the inheritable child end) and, for SLOT_PIPE, *parent
+ * (our end) + *parent_writable. */
+static void
+build_slot(int spec_kind, VALUE vio, int is_input,
+           HANDLE *child, HANDLE *parent, int *parent_writable)
+{
+    *child = NULL; *parent = NULL; *parent_writable = 0;
+    if (spec_kind == SLOT_PIPE) {
+        HANDLE r = NULL, w = NULL;
+        if (!CreatePipe(&r, &w, NULL, 0)) raise_gle("CreatePipe", GetLastError());
+        if (is_input) {
+            /* child reads r; parent writes w */
+            SetHandleInformation(r, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT);
+            *child = r; *parent = w; *parent_writable = 1;
+        } else {
+            /* child writes w; parent reads r */
+            SetHandleInformation(w, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT);
+            *child = w; *parent = r; *parent_writable = 0;
+        }
+    } else if (spec_kind == SLOT_NULL) {
+        HANDLE nul = open_nul_inheritable();
+        if (nul == INVALID_HANDLE_VALUE) raise_gle("CreateFile(NUL)", GetLastError());
+        *child = nul;
+    } else if (spec_kind == SLOT_IO) {
+        int fd = rb_io_descriptor(vio);
+        HANDLE src = (HANDLE)_get_osfhandle(fd);
+        HANDLE dup = NULL;
+        if (src == INVALID_HANDLE_VALUE)
+            rb_raise(rb_eArgError, "winproc: IO has no OS handle");
+        if (!DuplicateHandle(GetCurrentProcess(), src, GetCurrentProcess(), &dup,
+                             0, TRUE, DUPLICATE_SAME_ACCESS))
+            raise_gle("DuplicateHandle", GetLastError());
+        *child = dup;
+    } else { /* SLOT_INHERIT in redirected mode: duplicate the parent's std */
+        *child = inherit_std_or_nul(is_input ? STD_INPUT_HANDLE :
+                                    /* caller passes the right std via vio==stdno marker */
+                                    (DWORD)NUM2ULONG(vio));
+    }
+}
+
+/* Add h to the deduped HANDLE_LIST. */
+static void
+hlist_add(spawn_ctx *c, HANDLE h)
+{
+    DWORD i;
+    if (!h || h == INVALID_HANDLE_VALUE) return;
+    for (i = 0; i < c->hcount; i++) if (c->hlist[i] == h) return;
+    if (c->hcount < 3) c->hlist[c->hcount++] = h;
+}
+
+/*
+ * Winproc._spawn(app, cmdline, cwd, envblock, flags, job, pty_cols, pty_rows,
+ *                in_kind, in_io, out_kind, out_io, err_kind, err_io)
+ *
+ * flags: the extra CreationFlags bits the Ruby layer computed
+ *   (CREATE_NEW_PROCESS_GROUP / CREATE_NO_WINDOW). The base flags
+ *   (CREATE_UNICODE_ENVIRONMENT|EXTENDED_STARTUPINFO_PRESENT) are added here.
+ * pty_cols > 0 selects ConPTY mode (redirection kwargs are absent in that path).
+ * Returns the Process (redirected) or the PTY (pty mode).
+ */
+static VALUE
+winproc_spawn(int argc, VALUE *argv, VALUE self)
+{
+    spawn_ctx c;
+    VALUE v_app, v_cmd, v_cwd, v_env, v_flags, v_job,
+          v_pcols, v_prows, v_ik, v_iio, v_ok, v_oio, v_ek, v_eio;
+    DWORD base_flags, extra_flags;
+    int pty_mode;
+    BOOL inherit;
+    STARTUPINFOEXW si;
+    DWORD attr_count = 0;
+    DWORD need;
+    process_t *pr;
+    DWORD gle;
+
+    (void)self;
+    if (argc != 14) rb_raise(rb_eArgError, "winproc: _spawn arity");
+    v_app=argv[0]; v_cmd=argv[1]; v_cwd=argv[2]; v_env=argv[3]; v_flags=argv[4];
+    v_job=argv[5]; v_pcols=argv[6]; v_prows=argv[7];
+    v_ik=argv[8]; v_iio=argv[9]; v_ok=argv[10]; v_oio=argv[11]; v_ek=argv[12]; v_eio=argv[13];
+
+    memset(&c, 0, sizeof(c));
+    c.proc_obj = c.in_obj = c.out_obj = c.err_obj = Qnil;
+    c.pty_obj = c.pty_in_obj = c.pty_out_obj = Qnil;
+    c.pi.hProcess = NULL; c.pi.hThread = NULL;
+
+    extra_flags = (DWORD)NUM2ULONG(v_flags);
+    pty_mode = (NUM2INT(v_pcols) > 0);
+
+    /* ---- coerce strings up front (TypeError here: no HANDLE exists yet) ---- */
+    if (!NIL_P(v_app)) c.app = to_wide(v_app);
+    c.cmdline = to_wide(v_cmd); /* writable private copy (E-1) */
+    if (!NIL_P(v_cwd)) c.cwd = to_wide(v_cwd);
+    if (!NIL_P(v_env)) c.envblock = env_to_wide(v_env);
+    if (!NIL_P(v_job)) {
+        job_t *j;
+        if (!rb_typeddata_is_kind_of(v_job, &job_type)) {
+            spawn_cleanup_partial(&c);
+            rb_raise(rb_eTypeError, "winproc: job: must be a Winproc::Job");
+        }
+        j = job_get(v_job);
+        if (j->closed || !j->job) {
+            spawn_cleanup_partial(&c);
+            rb_raise(eClosed, "winproc: job is closed");
+        }
+        c.hjob = j->job;
+    }
+
+    memset(&si, 0, sizeof(si));
+    si.StartupInfo.cb = sizeof(STARTUPINFOEXW);
+    base_flags = CREATE_UNICODE_ENVIRONMENT | EXTENDED_STARTUPINFO_PRESENT;
+
+    if (pty_mode) {
+        COORD size;
+        HRESULT hr;
+        /* ConPTY availability is checked in Ruby (pty_available?); guard anyway. */
+        if (!p_CreatePseudoConsole) {
+            spawn_cleanup_partial(&c);
+            raise_code(eUnsupported, "CreatePseudoConsole", ERROR_PROC_NOT_FOUND);
+        }
+        size.X = (SHORT)NUM2INT(v_pcols); size.Y = (SHORT)NUM2INT(v_prows);
+        /* two pipes */
+        if (!CreatePipe(&c.pty_in_r, &c.pty_in_w, NULL, 0)) {
+            gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("CreatePipe", gle);
+        }
+        if (!CreatePipe(&c.pty_out_r, &c.pty_out_w, NULL, 0)) {
+            gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("CreatePipe", gle);
+        }
+        hr = p_CreatePseudoConsole(size, c.pty_in_r, c.pty_out_w, 0, &c.hpcon);
+        if (FAILED(hr)) {
+            spawn_cleanup_partial(&c);
+            raise_code(eOSError, "CreatePseudoConsole", (DWORD)(hr & 0xFFFF));
+        }
+        /* The PTY-side ends (pty_in_r / pty_out_w) are closed AFTER CreateProcess
+         * (E-8 / creating-a-pseudoconsole-session: "Upon completion of the
+         * CreateProcess call ... the handles given during creation should be
+         * freed from this process"). Closing them BEFORE CreateProcess can leave
+         * the child unattached. They are tracked in the ctx so the fail path also
+         * closes them. */
+        attr_count = 1 + (c.hjob ? 1 : 0);
+        inherit = FALSE; /* no STARTF_USESTDHANDLES, no HANDLE_LIST (E-9) */
+    } else {
+        /* ---- redirected/inherit mode: build the 3 child stdio handles ---- */
+        int ik = NUM2INT(v_ik), ok = NUM2INT(v_ok), ek = NUM2INT(v_ek);
+        int any_redirect = (ik != SLOT_INHERIT || ok != SLOT_INHERIT || ek != SLOT_INHERIT);
+        if (any_redirect) {
+            int pw;
+            HANDLE child, parent;
+            /* stdin */
+            if (ik == SLOT_INHERIT)
+                child = inherit_std_or_nul(STD_INPUT_HANDLE), parent = NULL;
+            else { build_slot(ik, v_iio, 1, &child, &parent, &pw); }
+            c.child_in = child;
+            if (ik == SLOT_PIPE) c.par_in_w = parent;
+            /* stdout */
+            if (ok == SLOT_INHERIT)
+                child = inherit_std_or_nul(STD_OUTPUT_HANDLE), parent = NULL;
+            else { build_slot(ok, v_oio, 0, &child, &parent, &pw); }
+            c.child_out = child;
+            if (ok == SLOT_PIPE) c.par_out_r = parent;
+            /* stderr (SLOT_MERGE => reuse stdout child handle) */
+            if (ek == SLOT_MERGE) {
+                c.child_err = c.child_out;
+            } else if (ek == SLOT_INHERIT) {
+                c.child_err = inherit_std_or_nul(STD_ERROR_HANDLE);
+            } else {
+                build_slot(ek, v_eio, 0, &child, &parent, &pw);
+                c.child_err = child;
+                if (ek == SLOT_PIPE) c.par_err_r = parent;
+            }
+
+            si.StartupInfo.dwFlags |= STARTF_USESTDHANDLES;
+            si.StartupInfo.hStdInput  = c.child_in;
+            si.StartupInfo.hStdOutput = c.child_out;
+            si.StartupInfo.hStdError  = c.child_err;
+            hlist_add(&c, c.child_in);
+            hlist_add(&c, c.child_out);
+            hlist_add(&c, c.child_err);
+            inherit = TRUE;
+            attr_count = 1 + (c.hjob ? 1 : 0); /* HANDLE_LIST + maybe JOB_LIST */
+        } else {
+            inherit = FALSE;
+            attr_count = (c.hjob ? 1 : 0);
+        }
+    }
+
+    /* ---- attribute list (E-4 double-call idiom) ---- */
+    if (attr_count > 0) {
+        need = 0;
+        InitializeProcThreadAttributeList(NULL, attr_count, 0, &c.attr_size);
+        c.attr = (LPPROC_THREAD_ATTRIBUTE_LIST)malloc(c.attr_size);
+        if (!c.attr) { spawn_cleanup_partial(&c); rb_raise(rb_eNoMemError, "winproc: out of memory"); }
+        if (!InitializeProcThreadAttributeList(c.attr, attr_count, 0, &c.attr_size)) {
+            gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("InitializeProcThreadAttributeList", gle);
+        }
+        c.attr_inited = 1;
+        (void)need;
+
+        if (pty_mode) {
+            if (!UpdateProcThreadAttribute(c.attr, 0, PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE,
+                                           c.hpcon, sizeof(c.hpcon), NULL, NULL)) {
+                gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("UpdateProcThreadAttribute(pty)", gle);
+            }
+        } else if (c.hcount > 0) {
+            if (!UpdateProcThreadAttribute(c.attr, 0, PROC_THREAD_ATTRIBUTE_HANDLE_LIST,
+                                           c.hlist, c.hcount * sizeof(HANDLE), NULL, NULL)) {
+                gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("UpdateProcThreadAttribute(handles)", gle);
+            }
+        }
+        if (c.hjob) {
+            if (!UpdateProcThreadAttribute(c.attr, 0, PROC_THREAD_ATTRIBUTE_JOB_LIST,
+                                           &c.hjob, sizeof(HANDLE), NULL, NULL)) {
+                gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("UpdateProcThreadAttribute(job)", gle);
+            }
+        }
+        si.lpAttributeList = c.attr;
+    }
+
+    /* ---- pre-allocate every raise-capable resource (E-31) ---- */
+    c.cancel_event = CreateEventW(NULL, TRUE, FALSE, NULL);
+    if (!c.cancel_event) { gle = GetLastError(); spawn_cleanup_partial(&c); raise_gle("CreateEvent", gle); }
+    c.proc_obj = process_alloc(cProcess);
+    if (pty_mode) {
+        c.pty_obj = pty_alloc(cPTY);
+        c.pty_in_obj = stream_alloc(cStream);   /* writable */
+        c.pty_out_obj = stream_alloc(cStream);  /* readable */
+        rb_ivar_set(c.pty_obj, rb_intern("@process"), c.proc_obj);
+        rb_ivar_set(c.pty_obj, rb_intern("@input"), c.pty_in_obj);
+        rb_ivar_set(c.pty_obj, rb_intern("@output"), c.pty_out_obj);
+    } else {
+        if (!NIL_P(v_ik) && NUM2INT(v_ik) == SLOT_PIPE) c.in_obj = stream_alloc(cStream);
+        if (NUM2INT(v_ok) == SLOT_PIPE) c.out_obj = stream_alloc(cStream);
+        if (NUM2INT(v_ek) == SLOT_PIPE) c.err_obj = stream_alloc(cStream);
+        if (!NIL_P(c.in_obj))  rb_ivar_set(c.proc_obj, rb_intern("@stdin"), c.in_obj);
+        if (!NIL_P(c.out_obj)) rb_ivar_set(c.proc_obj, rb_intern("@stdout"), c.out_obj);
+        if (!NIL_P(c.err_obj)) rb_ivar_set(c.proc_obj, rb_intern("@stderr"), c.err_obj);
+    }
+
+    /* ---- CreateProcessW (NO Ruby allocation past this point) ---- */
+    if (!CreateProcessW(c.app, c.cmdline, NULL, NULL, inherit,
+                        base_flags | extra_flags,
+                        c.envblock, c.cwd, &si.StartupInfo, &c.pi)) {
+        gle = GetLastError();
+        spawn_cleanup_partial(&c);
+        raise_gle("CreateProcessW", gle);
+    }
+    c.created = 1;
+
+    /* tidy attr list + child-side handles + pi.hThread (plain CloseHandle) */
+    if (c.attr_inited) { DeleteProcThreadAttributeList(c.attr); c.attr_inited = 0; }
+    if (c.attr) { free(c.attr); c.attr = NULL; }
+    if (c.pi.hThread) { CloseHandle(c.pi.hThread); c.pi.hThread = NULL; }
+    if (c.child_in)  { CloseHandle(c.child_in);  c.child_in = NULL; }
+    if (c.child_err && c.child_err != c.child_out) { CloseHandle(c.child_err); c.child_err = NULL; }
+    if (c.child_out) { CloseHandle(c.child_out); c.child_out = NULL; c.child_err = NULL; }
+    /* PTY-side ends: now that the child is attached, drop our refs so our read
+     * end can detect a broken channel (EOF) when the PTY tears down. */
+    if (c.pty_in_r)  { CloseHandle(c.pty_in_r);  c.pty_in_r  = NULL; }
+    if (c.pty_out_w) { CloseHandle(c.pty_out_w); c.pty_out_w = NULL; }
+
+    /* free wide strings */
+    if (c.app)      { xfree(c.app); c.app = NULL; }
+    if (c.cmdline)  { xfree(c.cmdline); c.cmdline = NULL; }
+    if (c.cwd)      { xfree(c.cwd); c.cwd = NULL; }
+    if (c.envblock) { xfree(c.envblock); c.envblock = NULL; }
+
+    /* ---- populate pre-allocated structs (plain stores; cannot raise) ---- */
+    pr = process_get(c.proc_obj);
+    pr->h = c.pi.hProcess;
+    pr->cancel_event = c.cancel_event;
+    pr->pid = c.pi.dwProcessId;
+    c.cancel_event = NULL; /* ownership moved to the Process */
+
+    if (pty_mode) {
+        pty_t *t = pty_get(c.pty_obj);
+        stream_t *sin = stream_get(c.pty_in_obj);
+        stream_t *sout = stream_get(c.pty_out_obj);
+        t->hpc = c.hpcon; c.hpcon = NULL;
+        t->cols = NUM2INT(v_pcols); t->rows = NUM2INT(v_prows);
+        sin->h = c.pty_in_w;  sin->writable = 1; c.pty_in_w = NULL;
+        sout->h = c.pty_out_r; sout->writable = 0; c.pty_out_r = NULL;
+        return c.pty_obj;
+    } else {
+        if (!NIL_P(c.in_obj))  { stream_t *s = stream_get(c.in_obj);  s->h = c.par_in_w;  s->writable = 1; c.par_in_w = NULL; }
+        if (!NIL_P(c.out_obj)) { stream_t *s = stream_get(c.out_obj); s->h = c.par_out_r; s->writable = 0; c.par_out_r = NULL; }
+        if (!NIL_P(c.err_obj)) { stream_t *s = stream_get(c.err_obj); s->h = c.par_err_r; s->writable = 0; c.par_err_r = NULL; }
+        return c.proc_obj;
+    }
+}
+
+/* =====================================================================
+ * Elevation helpers
+ * ===================================================================== */
+
+static VALUE
+winproc_elevated_p(VALUE self)
+{
+    HANDLE tok = NULL;
+    TOKEN_ELEVATION te;
+    DWORD n = 0;
+    BOOL elevated;
+    (void)self;
+    if (!OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &tok))
+        raise_gle("OpenProcessToken", GetLastError());
+    if (!GetTokenInformation(tok, TokenElevation, &te, sizeof(te), &n)) {
+        DWORD gle = GetLastError(); CloseHandle(tok);
+        raise_gle("GetTokenInformation(Elevation)", gle);
+    }
+    elevated = (te.TokenIsElevated != 0);
+    CloseHandle(tok);
+    return elevated ? Qtrue : Qfalse;
+}
+
+static VALUE
+winproc_admin_p(VALUE self)
+{
+    HANDLE tok = NULL, linked = NULL, check = NULL;
+    TOKEN_ELEVATION_TYPE et;
+    DWORD n = 0;
+    PSID sid = NULL;
+    SID_IDENTIFIER_AUTHORITY nt = SECURITY_NT_AUTHORITY;
+    BOOL member = FALSE;
+    DWORD gle;
+    (void)self;
+
+    if (!OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &tok))
+        raise_gle("OpenProcessToken", GetLastError());
+    if (!GetTokenInformation(tok, TokenElevationType, &et, sizeof(et), &n)) {
+        gle = GetLastError(); CloseHandle(tok); raise_gle("GetTokenInformation(ElevationType)", gle);
+    }
+    if (et == TokenElevationTypeLimited) {
+        TOKEN_LINKED_TOKEN lt;
+        memset(&lt, 0, sizeof(lt));
+        if (!GetTokenInformation(tok, TokenLinkedToken, &lt, sizeof(lt), &n)) {
+            gle = GetLastError(); CloseHandle(tok); raise_gle("GetTokenInformation(LinkedToken)", gle);
+        }
+        linked = lt.LinkedToken;     /* impersonation token already */
+        check = linked;
+    } else {
+        check = NULL;                /* NULL => effective token */
+    }
+    CloseHandle(tok);
+
+    if (!AllocateAndInitializeSid(&nt, 2, SECURITY_BUILTIN_DOMAIN_RID,
+                                  DOMAIN_ALIAS_RID_ADMINS, 0, 0, 0, 0, 0, 0, &sid)) {
+        gle = GetLastError(); if (linked) CloseHandle(linked); raise_gle("AllocateAndInitializeSid", gle);
+    }
+    if (!CheckTokenMembership(check, sid, &member)) {
+        gle = GetLastError(); FreeSid(sid); if (linked) CloseHandle(linked);
+        raise_gle("CheckTokenMembership", gle);
+    }
+    FreeSid(sid);
+    if (linked) CloseHandle(linked);
+    return member ? Qtrue : Qfalse;
+}
+
+static VALUE
+winproc_pty_available_p(VALUE self)
+{
+    (void)self;
+    return (p_CreatePseudoConsole && p_ResizePseudoConsole && p_ClosePseudoConsole)
+           ? Qtrue : Qfalse;
+}
+
+/* --- runas: ShellExecuteExW "runas" with COM init, GVL released ----------- */
+
+typedef struct {
+    WCHAR *file;
+    WCHAR *params;
+    WCHAR *dir;
+    int    nshow;
+    BOOL   ok;
+    DWORD  gle;
+    HANDLE hproc;
+} runas_t;
+
+static void *
+runas_fn(void *p)
+{
+    runas_t *r = (runas_t *)p;
+    SHELLEXECUTEINFOW sei;
+    HRESULT hr;
+    int balance_com = 0;
+
+    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
+    if (hr == S_OK || hr == S_FALSE) balance_com = 1;
+    /* RPC_E_CHANGED_MODE: COM already initialized differently; proceed, no uninit */
+
+    memset(&sei, 0, sizeof(sei));
+    sei.cbSize = sizeof(sei);
+    sei.fMask = SEE_MASK_NOCLOSEPROCESS | SEE_MASK_NOASYNC;
+    sei.lpVerb = L"runas";
+    sei.lpFile = r->file;
+    sei.lpParameters = r->params;
+    sei.lpDirectory = r->dir;
+    sei.nShow = r->nshow;
+
+    r->ok = ShellExecuteExW(&sei);
+    if (!r->ok) r->gle = GetLastError(); /* decode from GLE, never hInstApp (E-20) */
+    else r->hproc = sei.hProcess;        /* may be NULL even on success */
+
+    if (balance_com) CoUninitialize();
+    return NULL;
+}
+
+/* Winproc.__runas(exe_w8, params_w8, cwd_w8_or_nil, sw_int) -> Process | nil */
+static VALUE
+winproc_runas(VALUE self, VALUE vexe, VALUE vparams, VALUE vcwd, VALUE vsw)
+{
+    runas_t r;
+    VALUE obj;
+    process_t *pr;
+    (void)self;
+
+    memset(&r, 0, sizeof(r));
+    r.file = to_wide(vexe);
+    r.params = NIL_P(vparams) ? NULL : to_wide(vparams);
+    r.dir = NIL_P(vcwd) ? NULL : to_wide(vcwd);
+    r.nshow = NUM2INT(vsw);
+
+    rb_thread_call_without_gvl(runas_fn, &r, NULL, NULL);
+
+    {
+        DWORD gle = r.gle;
+        BOOL ok = r.ok;
+        HANDLE hproc = r.hproc;
+        if (r.file) xfree(r.file);
+        if (r.params) xfree(r.params);
+        if (r.dir) xfree(r.dir);
+        if (!ok) raise_gle("ShellExecuteExW", gle); /* 1223 -> Canceled */
+        if (hproc == NULL) return Qnil;             /* launched without a handle */
+
+        obj = process_alloc(cProcess);
+        pr = process_get(obj);
+        pr->h = hproc;
+        pr->pid = GetProcessId(hproc);
+        pr->cancel_event = CreateEventW(NULL, TRUE, FALSE, NULL);
+        if (!pr->cancel_event) {
+            DWORD e = GetLastError();
+            /* the Process owns hproc now; close it via process_close path */
+            CloseHandle(hproc); pr->h = INVALID_HANDLE_VALUE; pr->closed = 1;
+            raise_gle("CreateEvent", e);
+        }
+        return obj;
+    }
+}
+
+/* --- with_privilege: AdjustTokenPrivileges + the NOT_ALL_ASSIGNED check ---- */
+
+/* Winproc.__privilege(se_name_w8, enable_bool) -> prev_enabled_bool */
+static VALUE
+winproc_privilege(VALUE self, VALUE vname, VALUE venable)
+{
+    HANDLE tok = NULL;
+    WCHAR *name = to_wide(vname);
+    LUID luid;
+    TOKEN_PRIVILEGES tp, prev;
+    DWORD prev_len = sizeof(prev);
+    int enable = RTEST(venable);
+    int was_enabled;
+    DWORD gle;
+    (void)self;
+
+    if (!OpenProcessToken(GetCurrentProcess(),
+                          TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &tok)) {
+        gle = GetLastError(); xfree(name); raise_gle("OpenProcessToken", gle);
+    }
+    if (!LookupPrivilegeValueW(NULL, name, &luid)) {
+        gle = GetLastError(); xfree(name); CloseHandle(tok);
+        raise_gle("LookupPrivilegeValue", gle);
+    }
+    xfree(name);
+
+    memset(&tp, 0, sizeof(tp));
+    memset(&prev, 0, sizeof(prev));
+    tp.PrivilegeCount = 1;
+    tp.Privileges[0].Luid = luid;
+    tp.Privileges[0].Attributes = enable ? SE_PRIVILEGE_ENABLED : 0;
+
+    if (!AdjustTokenPrivileges(tok, FALSE, &tp, sizeof(prev), &prev, &prev_len)) {
+        gle = GetLastError(); CloseHandle(tok); raise_gle("AdjustTokenPrivileges", gle);
+    }
+    /* AdjustTokenPrivileges "succeeds" with ERROR_NOT_ALL_ASSIGNED even when the
+     * token doesn't hold the privilege — check GLE after success (E-19). */
+    gle = GetLastError();
+    if (gle == ERROR_NOT_ALL_ASSIGNED) {
+        CloseHandle(tok);
+        raise_code(ePrivilegeNotHeld, "AdjustTokenPrivileges", gle);
+    }
+    /* previous enabled-state from PreviousState (empty count => was disabled) */
+    was_enabled = (prev.PrivilegeCount >= 1 &&
+                   (prev.Privileges[0].Attributes & SE_PRIVILEGE_ENABLED)) ? 1 : 0;
+    CloseHandle(tok);
+    return was_enabled ? Qtrue : Qfalse;
+}
+
+/* ----------------------------------------------------------------- Init --- */
+
+void
+Init_winproc(void)
+{
+    HMODULE k32;
+
+    mWinproc = rb_define_module("Winproc");
+
+    eError             = rb_define_class_under(mWinproc, "Error", rb_eStandardError);
+    eOSError           = rb_define_class_under(mWinproc, "OSError", eError);
+    eNotFound          = rb_define_class_under(mWinproc, "NotFound", eOSError);
+    eAccessDenied      = rb_define_class_under(mWinproc, "AccessDenied", eOSError);
+    eCanceled          = rb_define_class_under(mWinproc, "Canceled", eOSError);
+    eBrokenPipe        = rb_define_class_under(mWinproc, "BrokenPipe", eOSError);
+    eElevationRequired = rb_define_class_under(mWinproc, "ElevationRequired", eOSError);
+    ePrivilegeNotHeld  = rb_define_class_under(mWinproc, "PrivilegeNotHeld", eOSError);
+    eUnsupported       = rb_define_class_under(mWinproc, "Unsupported", eOSError);
+    eModeError         = rb_define_class_under(mWinproc, "ModeError", eError);
+    eClosed            = rb_define_class_under(mWinproc, "Closed", eError);
+
+    /* module functions (primitives; underscore-private, wrapped in Ruby) */
+    rb_define_singleton_method(mWinproc, "_spawn", winproc_spawn, -1);
+    rb_define_singleton_method(mWinproc, "__elevated", winproc_elevated_p, 0);
+    rb_define_singleton_method(mWinproc, "__admin", winproc_admin_p, 0);
+    rb_define_singleton_method(mWinproc, "__pty_available", winproc_pty_available_p, 0);
+    rb_define_singleton_method(mWinproc, "__runas", winproc_runas, 4);
+    rb_define_singleton_method(mWinproc, "__privilege", winproc_privilege, 2);
+
+    /* Process */
+    cProcess = rb_define_class_under(mWinproc, "Process", rb_cObject);
+    rb_define_alloc_func(cProcess, process_alloc);
+    rb_define_method(cProcess, "initialize", process_initialize, -1);
+    rb_define_method(cProcess, "_wait", process_do_wait, 1);
+    rb_define_method(cProcess, "pid", process_pid, 0);
+    rb_define_method(cProcess, "alive?", process_alive_p, 0);
+    rb_define_method(cProcess, "exitstatus", process_exitstatus, 0);
+    rb_define_method(cProcess, "_kill", process_kill, -1);
+    rb_define_method(cProcess, "close", process_close, 0);
+    rb_define_method(cProcess, "closed?", process_closed_p, 0);
+
+    /* Job */
+    cJob = rb_define_class_under(mWinproc, "Job", rb_cObject);
+    rb_define_alloc_func(cJob, job_alloc);
+    rb_define_singleton_method(cJob, "_create", job_create, 6);
+    rb_define_method(cJob, "_assign", job_assign, 1);
+    rb_define_method(cJob, "_terminate", job_terminate, -1);
+    rb_define_method(cJob, "_wait_empty", job_wait_empty, 1);
+    rb_define_method(cJob, "active_processes", job_active_processes, 0);
+    rb_define_method(cJob, "close", job_close, 0);
+    rb_define_method(cJob, "closed?", job_closed_p, 0);
+
+    /* Stream */
+    cStream = rb_define_class_under(mWinproc, "Stream", rb_cObject);
+    rb_define_alloc_func(cStream, stream_alloc);
+    rb_define_method(cStream, "initialize", stream_initialize, -1);
+    rb_define_method(cStream, "_read", stream_read, 1);
+    rb_define_method(cStream, "_write", stream_write, 1);
+    rb_define_method(cStream, "writable?", stream_writable_p, 0);
+    rb_define_method(cStream, "close", stream_close, 0);
+    rb_define_method(cStream, "closed?", stream_closed_p, 0);
+
+    /* PTY */
+    cPTY = rb_define_class_under(mWinproc, "PTY", rb_cObject);
+    rb_define_alloc_func(cPTY, pty_alloc);
+    rb_define_method(cPTY, "initialize", pty_initialize, -1);
+    rb_define_method(cPTY, "_resize", pty_resize, 2);
+    rb_define_method(cPTY, "cols", pty_cols, 0);
+    rb_define_method(cPTY, "rows", pty_rows, 0);
+    rb_define_method(cPTY, "_close_pty", pty_close_pty, 0);
+    rb_define_method(cPTY, "closed?", pty_closed_p, 0);
+
+    /* SW_* show constants for runas (verified <winuser.h> values) */
+    rb_define_const(mWinproc, "SW_HIDE", INT2FIX(SW_HIDE));               /* 0 */
+    rb_define_const(mWinproc, "SW_SHOWNORMAL", INT2FIX(SW_SHOWNORMAL));   /* 1 */
+    rb_define_const(mWinproc, "SW_SHOWMINIMIZED", INT2FIX(SW_SHOWMINIMIZED)); /* 2 */
+    rb_define_const(mWinproc, "SW_SHOWMAXIMIZED", INT2FIX(SW_SHOWMAXIMIZED)); /* 3 */
+
+    /* CreateProcess creation-flag bits exposed to the Ruby layer (verified). */
+    rb_define_const(mWinproc, "CREATE_NEW_PROCESS_GROUP", ULONG2NUM(CREATE_NEW_PROCESS_GROUP));
+    rb_define_const(mWinproc, "CREATE_NO_WINDOW", ULONG2NUM(CREATE_NO_WINDOW));
+
+    /* stdio slot kinds shared with the Ruby layer */
+    rb_define_const(mWinproc, "SLOT_INHERIT", INT2FIX(SLOT_INHERIT));
+    rb_define_const(mWinproc, "SLOT_NULL", INT2FIX(SLOT_NULL));
+    rb_define_const(mWinproc, "SLOT_PIPE", INT2FIX(SLOT_PIPE));
+    rb_define_const(mWinproc, "SLOT_IO", INT2FIX(SLOT_IO));
+    rb_define_const(mWinproc, "SLOT_MERGE", INT2FIX(SLOT_MERGE));
+
+    /* Resolve ConPTY entry points at runtime (absent on Windows < 10 1809). */
+    k32 = GetModuleHandleW(L"kernel32.dll");
+    if (k32) {
+        p_CreatePseudoConsole = (PFN_CreatePseudoConsole)GetProcAddress(k32, "CreatePseudoConsole");
+        p_ResizePseudoConsole = (PFN_ResizePseudoConsole)GetProcAddress(k32, "ResizePseudoConsole");
+        p_ClosePseudoConsole  = (PFN_ClosePseudoConsole)GetProcAddress(k32, "ClosePseudoConsole");
+    }
+}