winsvc 0.1.0

data/ext/winsvc/winsvc.c

@@ -0,0 +1,1162 @@
+/*
+ * winsvc — host a Ruby process as a Windows service (SERVICE_WIN32_OWN_PROCESS)
+ * with correct service-control-manager integration, plus a minimal installer.
+ *
+ * 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. Two IRON RULES govern this file:
+ *
+ *   (1) SCM-OWNED THREADS NEVER TOUCH A SINGLE RUBY API. ServiceMain, HandlerEx,
+ *       and the dispatcher thread run on threads MRI did not create; MRI cannot
+ *       attach a foreign native thread (thread.c: rb_thread_call_with_gvl "DOES
+ *       NOT associate or convert a NON-Ruby thread to a Ruby thread"). Below the
+ *       review banner "/* ===== SCM-thread code: NO rb_ IDENTIFIERS BELOW =====",
+ *       no rb_* call may appear. Marshaling is memcpy -> fixed-size ring -> event
+ *       -> a real Ruby pump Thread that drains it into a Thread::Queue.
+ *   (2) SERVICE_STOPPED IS REPORTED EXACTLY ONCE, FROM ServiceMain, AFTER Ruby
+ *       has fully unwound. The first STOPPED report closes the RPC context handle
+ *       and "any subsequent calls can cause the process to crash" — so every
+ *       guard-check + SetServiceStatus pair (the handler's pending reports, the
+ *       Ruby status bridges, and ServiceMain's STOPPED report which sets
+ *       stopped_reported in the SAME critical section as the report) executes
+ *       atomically under the one host CRITICAL_SECTION.
+ *
+ * Native state is a process singleton (Win32 permits ONE StartServiceCtrlDispatcherW
+ * per process, ever), so all of it lives in one file-scope `static host_t g_host`,
+ * latched once by an interlocked one-shot and never freed (process-lifetime — the
+ * phylax CNG-handle precedent). The yielded Winsvc::Service is a plain Ruby object
+ * holding no native pointer. SCM-client calls (_install etc.) open and close every
+ * handle within a single C function call; nothing outlives a call.
+ *
+ * Arch-neutral: gated only on /mswin/ at extconf, _WIN64 here, ULONG_PTR for
+ * handle-sized values; no /MACHINE, no inline asm. Links advapi32 (+ kernel32
+ * by default). Include <ruby.h> before <windows.h>; never name a variable IN/OUT.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+#include <limits.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <process.h>   /* _beginthreadex */
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mWinsvc;
+static VALUE eError, eOSError, eAccessDenied, eExists, eNotFound,
+             eMarkedForDelete, eTimeout, eStateError;
+
+/* ----------------------------------------------------------- tunables -------*/
+
+#define WINSVC_RING_CAP   64    /* control-record ring slots                  */
+#define WINSVC_DATA_MAX   512   /* truncation cap for POWERBROADCAST_SETTING  */
+#define WINSVC_DRAIN_MAX  8     /* records copied per CS hold in _wait_control */
+
+/* Win32 numeric constants we use that may be absent from older SDK headers. */
+#ifndef SERVICE_ACCEPT_PRESHUTDOWN
+#define SERVICE_ACCEPT_PRESHUTDOWN 0x00000100
+#endif
+#ifndef SERVICE_CONTROL_PRESHUTDOWN
+#define SERVICE_CONTROL_PRESHUTDOWN 0x0000000F
+#endif
+#ifndef SERVICE_CONFIG_DELAYED_AUTO_START_INFO
+#define SERVICE_CONFIG_DELAYED_AUTO_START_INFO 3
+#endif
+#ifndef SERVICE_CONFIG_PRESHUTDOWN_INFO
+#define SERVICE_CONFIG_PRESHUTDOWN_INFO 7
+#endif
+#ifndef SERVICE_CONFIG_FAILURE_ACTIONS_FLAG
+#define SERVICE_CONFIG_FAILURE_ACTIONS_FLAG 4
+#endif
+
+/* ------------------------------------------------------------ native types -*/
+
+/* Fixed-size control record; copied by value, never pointed-to. No pointers,
+ * nothing to free, no ABA. */
+typedef struct {
+    DWORD control;                  /* SERVICE_CONTROL_*                       */
+    DWORD event_type;               /* PBT_* / WTS_* or 0                      */
+    DWORD session_id;               /* dwSessionId, or 0xFFFFFFFF = none       */
+    DWORD data_len;                 /* 0..WINSVC_DATA_MAX                      */
+    BYTE  data[WINSVC_DATA_MAX];    /* POWERBROADCAST_SETTING bytes (truncated)*/
+    ULONGLONG tick;                 /* GetTickCount64 at enqueue (diagnostic)  */
+} ctl_rec_t;
+
+typedef struct {
+    LONG   used;                    /* one-shot latch (InterlockedCompareExchange) */
+    WCHAR *name_w;                  /* malloc'd; must outlive the dispatcher call  */
+    DWORD  accept_mask, start_hint, stop_hint;
+
+    /* SCM/dispatcher -> Ruby signalling */
+    HANDLE hStarted;                /* manual-reset: ServiceMain entered (service) */
+    HANDLE hConsoleMode;            /* manual-reset: dispatcher saw 1063 (console) */
+    HANDLE hDispatchFail;           /* manual-reset: dispatcher failed (!= 1063)   */
+    HANDLE hControl;                /* auto-reset:   ring has data                 */
+    HANDLE hPumpWake;               /* auto-reset:   ubf wake for _wait_control    */
+    HANDLE hMainWake;               /* auto-reset:   ubf wake for _host_wait_mode  */
+    HANDLE hRubyDone;               /* manual-reset: Ruby unwound -> report STOPPED*/
+    HANDLE hDispatcher;             /* _beginthreadex handle, joined in _host_done */
+
+    SERVICE_STATUS_HANDLE status;   /* registered in ServiceMain; never closed     */
+    CRITICAL_SECTION lock;          /* guards ring + state/checkpoint + EVERY
+                                       SetServiceStatus (handler, bridges, ServiceMain) */
+
+    ctl_rec_t ring[WINSVC_RING_CAP];
+    unsigned  head, count, dropped;
+
+    DWORD  current_state, checkpoint; /* last reported state, for _checkpoint      */
+    LONG   stop_flag;               /* set by handler on STOP/SHUTDOWN/PRESHUTDOWN */
+    LONG   stopped_reported;        /* hard guard; set under lock WITH the STOPPED report */
+    DWORD  win32_exit, specific_exit;
+
+    DWORD  dispatch_error;          /* GetLastError when the dispatcher failed (!=1063) */
+
+    char **argv_utf8;               /* ServiceMain args (plain malloc — no Ruby on   */
+    int    argc;                    /* an SCM thread; OOM must not longjmp)           */
+} host_t;
+
+static host_t g_host;               /* the process singleton; never freed */
+
+/* ============================================================================
+ *  SCM-thread code: NO rb_ IDENTIFIERS BELOW THIS BANNER (rule 1).
+ *  These functions run on SCM-created native threads (ServiceMain, HandlerEx)
+ *  or on our own dispatcher thread, which must never enter the Ruby VM either.
+ *  Plain malloc/memcpy only; no xmalloc, no rb_*.
+ * ==========================================================================*/
+
+/* Report status under the host lock. The caller decides the guard policy; this
+ * helper just fills the struct and calls SetServiceStatus. NOT locked here —
+ * callers hold the CS so the guard check + report are atomic. */
+static void
+report_status_locked(DWORD state, DWORD accepted, DWORD checkpoint,
+                     DWORD wait_hint, DWORD win32_exit, DWORD specific)
+{
+    SERVICE_STATUS ss;
+    ss.dwServiceType             = SERVICE_WIN32_OWN_PROCESS;
+    ss.dwCurrentState            = state;
+    ss.dwControlsAccepted        = accepted;
+    ss.dwWin32ExitCode           = win32_exit;
+    ss.dwServiceSpecificExitCode = specific;
+    ss.dwCheckPoint              = checkpoint;
+    ss.dwWaitHint                = wait_hint;
+    if (g_host.status) SetServiceStatus(g_host.status, &ss);
+    g_host.current_state = state;
+    g_host.checkpoint    = checkpoint;
+}
+
+/* Enqueue a control record into the ring. Shared VERBATIM by HandlerEx and the
+ * Ruby _inject bridge (which calls it under the same CS). Stop-class records
+ * overwrite the newest slot when full (guaranteed delivery — the latched
+ * stop_flag is the real signal anyway); anything else is dropped + counted.
+ * Caller need NOT hold the lock; this acquires it (the CS is recursive, so the
+ * handler's outer hold nests fine). Signals hControl after releasing. */
+static int
+enqueue_rec(const ctl_rec_t *rec)
+{
+    int is_stop = (rec->control == SERVICE_CONTROL_STOP ||
+                   rec->control == SERVICE_CONTROL_SHUTDOWN ||
+                   rec->control == SERVICE_CONTROL_PRESHUTDOWN);
+    EnterCriticalSection(&g_host.lock);
+    if (g_host.count >= WINSVC_RING_CAP) {
+        if (is_stop) {
+            /* Overwrite the newest slot so the stop is never lost. The displaced
+             * record IS lost, so count it as dropped — keeping the invariant
+             * delivered + dropped == injected exact. */
+            unsigned newest = (g_host.head + g_host.count - 1) % WINSVC_RING_CAP;
+            g_host.ring[newest] = *rec;
+            g_host.dropped++;
+        } else {
+            g_host.dropped++;
+        }
+    } else {
+        unsigned slot = (g_host.head + g_host.count) % WINSVC_RING_CAP;
+        g_host.ring[slot] = *rec;
+        g_host.count++;
+    }
+    LeaveCriticalSection(&g_host.lock);
+    SetEvent(g_host.hControl);
+    return is_stop;
+}
+
+/* HandlerEx — the hot path. Pure C, microseconds. Runs on the dispatcher thread;
+ * the SCM serializes control delivery. */
+static DWORD WINAPI
+handler_ex(DWORD dwControl, DWORD dwEventType, LPVOID lpEventData, LPVOID lpContext)
+{
+    ctl_rec_t rec;
+    (void)lpContext;
+
+    switch (dwControl) {
+    case SERVICE_CONTROL_INTERROGATE:
+        /* The SCM caches the last reported status; no re-report needed. */
+        return NO_ERROR;
+
+    case SERVICE_CONTROL_STOP:
+    case SERVICE_CONTROL_SHUTDOWN:
+    case SERVICE_CONTROL_PRESHUTDOWN:
+        EnterCriticalSection(&g_host.lock);
+        if (!g_host.stopped_reported) {
+            report_status_locked(SERVICE_STOP_PENDING, 0, 1, g_host.stop_hint,
+                                 NO_ERROR, 0);
+            InterlockedExchange(&g_host.stop_flag, 1);
+            memset(&rec, 0, sizeof(rec));
+            rec.control    = dwControl;
+            rec.session_id = 0xFFFFFFFF;
+            rec.tick       = GetTickCount64();
+            enqueue_rec(&rec);   /* recursive CS: nests fine */
+        }
+        LeaveCriticalSection(&g_host.lock);
+        return NO_ERROR;
+
+    case SERVICE_CONTROL_PAUSE:
+    case SERVICE_CONTROL_CONTINUE:
+        EnterCriticalSection(&g_host.lock);
+        if (!g_host.stopped_reported) {
+            DWORD pending = (dwControl == SERVICE_CONTROL_PAUSE)
+                          ? SERVICE_PAUSE_PENDING : SERVICE_CONTINUE_PENDING;
+            report_status_locked(pending, 0, 1, g_host.stop_hint, NO_ERROR, 0);
+            memset(&rec, 0, sizeof(rec));
+            rec.control    = dwControl;
+            rec.session_id = 0xFFFFFFFF;
+            rec.tick       = GetTickCount64();
+            enqueue_rec(&rec);
+        }
+        LeaveCriticalSection(&g_host.lock);
+        return NO_ERROR;
+
+    case SERVICE_CONTROL_POWEREVENT:
+        memset(&rec, 0, sizeof(rec));
+        rec.control    = dwControl;
+        rec.event_type = dwEventType;
+        rec.session_id = 0xFFFFFFFF;
+        rec.tick       = GetTickCount64();
+        if (dwEventType == PBT_POWERSETTINGCHANGE && lpEventData) {
+            /* POWERBROADCAST_SETTING { GUID; DWORD DataLength; UCHAR Data[1] }.
+             * Copy the header + DataLength bytes, capped. The pointer is valid
+             * ONLY during this call. */
+            POWERBROADCAST_SETTING *pbs = (POWERBROADCAST_SETTING *)lpEventData;
+            DWORD hdr = (DWORD)(sizeof(GUID) + sizeof(DWORD));
+            DWORD total = hdr + pbs->DataLength;
+            if (total > WINSVC_DATA_MAX) total = WINSVC_DATA_MAX;
+            memcpy(rec.data, lpEventData, total);
+            rec.data_len = total;
+        }
+        enqueue_rec(&rec);
+        return NO_ERROR;
+
+    case SERVICE_CONTROL_SESSIONCHANGE:
+        memset(&rec, 0, sizeof(rec));
+        rec.control    = dwControl;
+        rec.event_type = dwEventType;
+        rec.session_id = 0xFFFFFFFF;
+        rec.tick       = GetTickCount64();
+        if (lpEventData) {
+            WTSSESSION_NOTIFICATION *wsn = (WTSSESSION_NOTIFICATION *)lpEventData;
+            rec.session_id = wsn->dwSessionId;
+        }
+        enqueue_rec(&rec);
+        return NO_ERROR;
+
+    default:
+        return ERROR_CALL_NOT_IMPLEMENTED;
+    }
+}
+
+/* ServiceMain — runs on an SCM-created thread. Pure C. */
+static void WINAPI
+service_main(DWORD dwArgc, LPWSTR *lpszArgv)
+{
+    DWORD i;
+
+    g_host.status = RegisterServiceCtrlHandlerExW(g_host.name_w, handler_ex, NULL);
+    if (!g_host.status) {
+        /* Cannot report status without a handle. The dispatcher will fail the
+         * service; surface "console-ish" by setting hDispatchFail. */
+        g_host.dispatch_error = GetLastError();
+        SetEvent(g_host.hDispatchFail);
+        return;
+    }
+
+    /* Initial report: accepted MUST be 0 while START_PENDING, or the service
+     * can crash. */
+    EnterCriticalSection(&g_host.lock);
+    report_status_locked(SERVICE_START_PENDING, 0, 1, g_host.start_hint, NO_ERROR, 0);
+    LeaveCriticalSection(&g_host.lock);
+
+    /* Copy argv UTF-16 -> UTF-8 into plain-malloc'd buffers (no Ruby here). */
+    g_host.argc = (int)dwArgc;
+    if (dwArgc > 0) {
+        g_host.argv_utf8 = (char **)calloc(dwArgc, sizeof(char *));
+        if (g_host.argv_utf8) {
+            for (i = 0; i < dwArgc; i++) {
+                int n = WideCharToMultiByte(CP_UTF8, 0, lpszArgv[i], -1,
+                                            NULL, 0, NULL, NULL);
+                if (n > 0) {
+                    char *s = (char *)malloc((size_t)n);
+                    if (s) {
+                        WideCharToMultiByte(CP_UTF8, 0, lpszArgv[i], -1,
+                                            s, n, NULL, NULL);
+                    }
+                    g_host.argv_utf8[i] = s; /* may be NULL on OOM; Ruby treats as "" */
+                }
+            }
+        } else {
+            g_host.argc = 0; /* OOM: present no args rather than crash */
+        }
+    }
+
+    SetEvent(g_host.hStarted);
+
+    /* Wait for Ruby to fully unwind, then report STOPPED exactly once. */
+    WaitForSingleObject(g_host.hRubyDone, INFINITE);
+
+    EnterCriticalSection(&g_host.lock);
+    g_host.stopped_reported = 1;  /* set WITH the report, atomically (rule 2) */
+    report_status_locked(SERVICE_STOPPED, 0, 0, 0,
+                         g_host.win32_exit, g_host.specific_exit);
+    LeaveCriticalSection(&g_host.lock);
+    /* No further work after STOPPED: the process may be terminated at any time. */
+}
+
+/* The dispatcher thread. _beginthreadex entry. Pure C. */
+static unsigned __stdcall
+dispatcher_thread(void *arg)
+{
+    SERVICE_TABLE_ENTRYW table[2];
+    (void)arg;
+
+    table[0].lpServiceName = g_host.name_w; /* ignored for OWN_PROCESS, must be valid */
+    table[0].lpServiceProc = service_main;
+    table[1].lpServiceName = NULL;
+    table[1].lpServiceProc = NULL;
+
+    if (!StartServiceCtrlDispatcherW(table)) {
+        DWORD gle = GetLastError();
+        if (gle == ERROR_FAILED_SERVICE_CONTROLLER_CONNECT) {
+            SetEvent(g_host.hConsoleMode);   /* 1063 — launched from a console/CI */
+        } else {
+            g_host.dispatch_error = gle;
+            SetEvent(g_host.hDispatchFail);
+        }
+    }
+    /* Success path: returns only once the service is STOPPED. */
+    return 0;
+}
+
+/* ============================================================================
+ *  Ruby-thread code below: rb_* allowed again. These run on the Ruby main
+ *  thread or the pump Thread.
+ * ==========================================================================*/
+
+/* UTF-8 Ruby String -> freshly xmalloc'd NUL-terminated UTF-16. Caller xfrees.
+ * (winipc to_wide, verbatim.) */
+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, "winsvc: 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;
+}
+
+/* Plain-malloc'd NUL-terminated UTF-16 (for the dispatcher's name_w, which must
+ * outlive the call and never be touched by Ruby's GC). Returns NULL on failure. */
+static WCHAR *
+to_wide_malloc(VALUE str)
+{
+    int len, n;
+    WCHAR *w;
+    StringValue(str);
+    len = (int)RSTRING_LEN(str);
+    n = (len == 0) ? 0 : MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, NULL, 0);
+    if (len != 0 && n <= 0) return NULL;
+    w = (WCHAR *)malloc(sizeof(WCHAR) * (size_t)(n + 1));
+    if (!w) return NULL;
+    if (n > 0) MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, w, n);
+    w[n] = 0;
+    return w;
+}
+
+/* Build + raise a winsvc error carrying @code (the Win32 error). The code must
+ * be captured by the caller immediately after the failing syscall. (winipc
+ * raise_code, verbatim shape — release the OS buffer before any Ruby alloc.) */
+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;
+    }
+    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_ACCESS_DENIED:                klass = eAccessDenied;     break; /* 5    */
+        case ERROR_SERVICE_EXISTS:                                                  /* 1073 */
+        case ERROR_DUPLICATE_SERVICE_NAME:        klass = eExists;          break; /* 1078 */
+        case ERROR_SERVICE_DOES_NOT_EXIST:        klass = eNotFound;        break; /* 1060 */
+        case ERROR_SERVICE_MARKED_FOR_DELETE:     klass = eMarkedForDelete; break; /* 1072 */
+        default: break;
+    }
+    raise_code(klass, api, code);
+}
+
+/* ----------------------------------------------------- _host_start ---------*/
+
+/* Winsvc._host_start(name, accept_mask, start_hint, stop_hint) -> true
+ * Create events/CS/ring, spawn the dispatcher thread. One-shot interlocked
+ * latch: a second call raises StateError before touching the OS. */
+static VALUE
+host_start(VALUE mod, VALUE name, VALUE accept_mask, VALUE start_hint, VALUE stop_hint)
+{
+    DWORD mask  = NUM2ULONG(accept_mask);
+    DWORD shint = NUM2ULONG(start_hint);
+    DWORD phint = NUM2ULONG(stop_hint);
+    WCHAR *nw;
+    uintptr_t th;
+    (void)mod;
+
+    if (InterlockedCompareExchange(&g_host.used, 1, 0) != 0)
+        rb_raise(eStateError, "winsvc: Winsvc.run may be called only once per process");
+
+    nw = to_wide_malloc(name);
+    if (!nw) {
+        g_host.used = 1; /* stays latched; this process can never host again */
+        rb_raise(eError, "winsvc: invalid UTF-8 in service name");
+    }
+    g_host.name_w     = nw;
+    g_host.accept_mask = mask;
+    g_host.start_hint  = shint;
+    g_host.stop_hint   = phint;
+
+    InitializeCriticalSection(&g_host.lock);
+
+    /* manual-reset: hStarted, hConsoleMode, hDispatchFail, hRubyDone.
+     * auto-reset:   hControl, hPumpWake, hMainWake. (7 total) */
+    g_host.hStarted      = CreateEventW(NULL, TRUE,  FALSE, NULL);
+    g_host.hConsoleMode  = CreateEventW(NULL, TRUE,  FALSE, NULL);
+    g_host.hDispatchFail = CreateEventW(NULL, TRUE,  FALSE, NULL);
+    g_host.hRubyDone     = CreateEventW(NULL, TRUE,  FALSE, NULL);
+    g_host.hControl      = CreateEventW(NULL, FALSE, FALSE, NULL);
+    g_host.hPumpWake     = CreateEventW(NULL, FALSE, FALSE, NULL);
+    g_host.hMainWake     = CreateEventW(NULL, FALSE, FALSE, NULL);
+    if (!g_host.hStarted || !g_host.hConsoleMode || !g_host.hDispatchFail ||
+        !g_host.hRubyDone || !g_host.hControl || !g_host.hPumpWake || !g_host.hMainWake)
+        raise_gle("CreateEvent", GetLastError());
+
+    th = _beginthreadex(NULL, 0, dispatcher_thread, NULL, 0, NULL);
+    if (th == 0)
+        rb_raise(eError, "winsvc: failed to start the dispatcher thread");
+    g_host.hDispatcher = (HANDLE)th;
+
+    return Qtrue;
+}
+
+/* ----------------------------------------------- _host_wait_mode -----------*/
+
+typedef struct { DWORD which; } mode_wait_t;
+
+static void *
+mode_wait_fn(void *p)
+{
+    mode_wait_t *w = (mode_wait_t *)p;
+    HANDLE hs[4];
+    hs[0] = g_host.hStarted;
+    hs[1] = g_host.hConsoleMode;
+    hs[2] = g_host.hDispatchFail;
+    hs[3] = g_host.hMainWake;
+    w->which = WaitForMultipleObjects(4, hs, FALSE, INFINITE);
+    return NULL;
+}
+
+static void
+mode_wait_ubf(void *p)
+{
+    (void)p;
+    SetEvent(g_host.hMainWake);
+}
+
+/* Winsvc._host_wait_mode -> :service | :console  (raises OSError on dispatch
+ * failure). GVL released; ubf wakes via hMainWake so Thread#kill / Ctrl-C break
+ * it, then we re-wait. */
+static VALUE
+host_wait_mode(VALUE mod)
+{
+    (void)mod;
+    for (;;) {
+        mode_wait_t w;
+        w.which = WAIT_FAILED;
+        rb_thread_call_without_gvl(mode_wait_fn, &w, mode_wait_ubf, &w);
+
+        if (w.which == WAIT_OBJECT_0 + 0)
+            return ID2SYM(rb_intern("service"));
+        if (w.which == WAIT_OBJECT_0 + 1)
+            return ID2SYM(rb_intern("console"));
+        if (w.which == WAIT_OBJECT_0 + 2)
+            raise_gle("StartServiceCtrlDispatcher", g_host.dispatch_error);
+
+        /* hMainWake (index 3) or WAIT_FAILED: service interrupts, then re-wait. */
+        rb_thread_check_ints();
+    }
+}
+
+/* ----------------------------------------------------- _host_args ----------*/
+
+/* Winsvc._host_args -> Array<String> (frozen UTF-8), the ServiceMain argv. */
+static VALUE
+host_args(VALUE mod)
+{
+    VALUE ary;
+    int i;
+    (void)mod;
+    ary = rb_ary_new_capa(g_host.argc > 0 ? g_host.argc : 0);
+    for (i = 0; i < g_host.argc; i++) {
+        const char *s = g_host.argv_utf8 ? g_host.argv_utf8[i] : NULL;
+        VALUE str = rb_utf8_str_new_cstr(s ? s : "");
+        rb_str_freeze(str);
+        rb_ary_push(ary, str);
+    }
+    return ary;
+}
+
+/* ---------------------------------------------------- _wait_control --------*/
+
+typedef struct { DWORD ms; DWORD which; } ctl_wait_t;
+
+static void *
+ctl_wait_fn(void *p)
+{
+    ctl_wait_t *w = (ctl_wait_t *)p;
+    HANDLE hs[2];
+    hs[0] = g_host.hControl;
+    hs[1] = g_host.hPumpWake;
+    w->which = WaitForMultipleObjects(2, hs, FALSE, w->ms);
+    return NULL;
+}
+
+static void
+ctl_wait_ubf(void *p)
+{
+    (void)p;
+    SetEvent(g_host.hPumpWake);
+}
+
+/* Build a Ruby Array of raw-record arrays from one drain chunk. Called with the
+ * GVL held and NO critical section held (records already copied to the stack). */
+static VALUE
+build_records(const ctl_rec_t *recs, int n)
+{
+    VALUE out = rb_ary_new_capa(n);
+    int i;
+    for (i = 0; i < n; i++) {
+        const ctl_rec_t *r = &recs[i];
+        VALUE row = rb_ary_new_capa(6);
+        VALUE data;
+        rb_ary_push(row, ULONG2NUM(r->control));
+        rb_ary_push(row, ULONG2NUM(r->event_type));
+        rb_ary_push(row, ULONG2NUM(r->session_id));
+        if (r->data_len > 0) {
+            data = rb_str_new((const char *)r->data, (long)r->data_len);
+            rb_enc_associate(data, rb_ascii8bit_encoding());
+            rb_str_freeze(data);
+        } else {
+            data = Qnil;
+        }
+        rb_ary_push(row, data);
+        rb_ary_push(row, ULL2NUM(r->tick));
+        rb_ary_freeze(row);
+        rb_ary_push(out, row);
+    }
+    return out;
+}
+
+/* Winsvc._wait_control(ms) -> Array of raw records, or nil on timeout.
+ * (-1 ms == INFINITE.) Drains up to WINSVC_DRAIN_MAX records per CS hold,
+ * building Ruby objects OUTSIDE the lock (no Ruby allocation while the CS is
+ * held — an OOM longjmp must not orphan the lock), looping until the ring is
+ * empty. */
+static VALUE
+wait_control(VALUE mod, VALUE vms)
+{
+    long ms_in = NUM2LONG(vms);
+    ctl_wait_t w;
+    VALUE all = Qnil;
+    (void)mod;
+
+    w.ms = (ms_in < 0) ? INFINITE : (DWORD)ms_in;
+    w.which = WAIT_FAILED;
+    rb_thread_call_without_gvl(ctl_wait_fn, &w, ctl_wait_ubf, &w);
+
+    if (w.which == WAIT_TIMEOUT) {
+        rb_thread_check_ints();
+        return Qnil;
+    }
+    /* hPumpWake (ubf) or signaled hControl: service interrupts (delivers the
+     * teardown Thread#kill), then drain whatever is present. */
+    rb_thread_check_ints();
+
+    for (;;) {
+        ctl_rec_t chunk[WINSVC_DRAIN_MAX];
+        int got = 0;
+        VALUE part;
+
+        EnterCriticalSection(&g_host.lock);
+        while (got < WINSVC_DRAIN_MAX && g_host.count > 0) {
+            chunk[got++] = g_host.ring[g_host.head];
+            g_host.head = (g_host.head + 1) % WINSVC_RING_CAP;
+            g_host.count--;
+        }
+        LeaveCriticalSection(&g_host.lock);
+
+        if (got == 0) break;
+        part = build_records(chunk, got);     /* Ruby alloc, lock released */
+        if (NIL_P(all)) all = part;
+        else rb_ary_concat(all, part);
+        if (got < WINSVC_DRAIN_MAX) break;    /* ring drained this pass */
+    }
+    return all; /* may be nil if a spurious wake found nothing */
+}
+
+/* ------------------------------------------------------- _inject -----------*/
+
+/* Winsvc._inject(control, event_type, session_id, data_or_nil) -> true
+ * Enqueue a record from Ruby (console Ctrl-C; tests) — the SAME enqueue path
+ * HandlerEx uses, under the same CS. Reports the pending transition for
+ * stop/pause/continue exactly like the handler, so console mode and tests see
+ * the real state machine. */
+static VALUE
+host_inject(VALUE mod, VALUE vcontrol, VALUE vevent, VALUE vsession, VALUE vdata)
+{
+    ctl_rec_t rec;
+    DWORD control = NUM2ULONG(vcontrol);
+    (void)mod;
+
+    memset(&rec, 0, sizeof(rec));
+    rec.control    = control;
+    rec.event_type = NIL_P(vevent) ? 0 : NUM2ULONG(vevent);
+    rec.session_id = NIL_P(vsession) ? 0xFFFFFFFF : NUM2ULONG(vsession);
+    rec.tick       = GetTickCount64();
+    if (!NIL_P(vdata)) {
+        long len;
+        StringValue(vdata);
+        len = RSTRING_LEN(vdata);
+        if (len > WINSVC_DATA_MAX) len = WINSVC_DATA_MAX;
+        memcpy(rec.data, RSTRING_PTR(vdata), (size_t)len);
+        rec.data_len = (DWORD)len;
+    }
+
+    EnterCriticalSection(&g_host.lock);
+    if (!g_host.stopped_reported) {
+        if (control == SERVICE_CONTROL_STOP ||
+            control == SERVICE_CONTROL_SHUTDOWN ||
+            control == SERVICE_CONTROL_PRESHUTDOWN) {
+            if (g_host.status)
+                report_status_locked(SERVICE_STOP_PENDING, 0, 1, g_host.stop_hint, NO_ERROR, 0);
+            InterlockedExchange(&g_host.stop_flag, 1);
+        } else if (control == SERVICE_CONTROL_PAUSE) {
+            if (g_host.status)
+                report_status_locked(SERVICE_PAUSE_PENDING, 0, 1, g_host.stop_hint, NO_ERROR, 0);
+        } else if (control == SERVICE_CONTROL_CONTINUE) {
+            if (g_host.status)
+                report_status_locked(SERVICE_CONTINUE_PENDING, 0, 1, g_host.stop_hint, NO_ERROR, 0);
+        }
+        enqueue_rec(&rec); /* recursive CS */
+    }
+    LeaveCriticalSection(&g_host.lock);
+    return Qtrue;
+}
+
+/* ------------------------------------------ status bridges (running etc.) --*/
+
+/* All status bridges: guard check + SetServiceStatus atomic under the host CS.
+ * In console mode g_host.status is NULL, so report_status_locked is a no-op —
+ * but the Ruby layer already no-ops these in console mode; the NULL guard is
+ * belt-and-suspenders. */
+
+static VALUE
+set_running(VALUE mod)
+{
+    (void)mod;
+    EnterCriticalSection(&g_host.lock);
+    /* running!/ready! no-op once a stop-class control is latched or after STOPPED. */
+    if (!g_host.stopped_reported && !g_host.stop_flag && g_host.status)
+        report_status_locked(SERVICE_RUNNING, g_host.accept_mask, 0, 0, NO_ERROR, 0);
+    LeaveCriticalSection(&g_host.lock);
+    return Qnil;
+}
+
+static VALUE
+set_paused(VALUE mod)
+{
+    (void)mod;
+    EnterCriticalSection(&g_host.lock);
+    if (!g_host.stopped_reported && !g_host.stop_flag && g_host.status)
+        report_status_locked(SERVICE_PAUSED, g_host.accept_mask, 0, 0, NO_ERROR, 0);
+    LeaveCriticalSection(&g_host.lock);
+    return Qnil;
+}
+
+/* Winsvc._checkpoint(hint_or_-1) -> true. Re-reports the CURRENT pending state
+ * with ++checkpoint. No-op when no transition is pending (a checkpoint in
+ * RUNNING/PAUSED/STOPPED is invalid). Keeps working after a stop is latched —
+ * that is exactly what a draining stop needs. */
+static VALUE
+checkpoint(VALUE mod, VALUE vhint)
+{
+    long hint_in = NUM2LONG(vhint);
+    (void)mod;
+    EnterCriticalSection(&g_host.lock);
+    if (!g_host.stopped_reported && g_host.status) {
+        DWORD st = g_host.current_state;
+        if (st == SERVICE_START_PENDING || st == SERVICE_STOP_PENDING ||
+            st == SERVICE_PAUSE_PENDING  || st == SERVICE_CONTINUE_PENDING) {
+            DWORD hint = (hint_in < 0) ? g_host.stop_hint : (DWORD)hint_in;
+            report_status_locked(st, 0, g_host.checkpoint + 1, hint, NO_ERROR, 0);
+        }
+    }
+    LeaveCriticalSection(&g_host.lock);
+    return Qnil;
+}
+
+/* Winsvc._stop_requested -> true|false (lock-free interlocked read). */
+static VALUE
+stop_requested(VALUE mod)
+{
+    (void)mod;
+    return InterlockedCompareExchange(&g_host.stop_flag, 0, 0) ? Qtrue : Qfalse;
+}
+
+/* Winsvc._dropped_count -> Integer (ring-overflow counter; diagnostics). */
+static VALUE
+dropped_count(VALUE mod)
+{
+    unsigned d;
+    (void)mod;
+    EnterCriticalSection(&g_host.lock);
+    d = g_host.dropped;
+    LeaveCriticalSection(&g_host.lock);
+    return UINT2NUM(d);
+}
+
+/* --------------------------------------------------------- _host_done ------*/
+
+typedef struct { HANDLE h; } join_t;
+
+static void *
+join_fn(void *p)
+{
+    join_t *j = (join_t *)p;
+    WaitForSingleObject(j->h, INFINITE);
+    return NULL;
+}
+
+/* Winsvc._host_done(specific_exit) -> true. Record the exit code, SetEvent
+ * hRubyDone (ServiceMain reports STOPPED), then JOIN the dispatcher thread.
+ *
+ * NULL ubf, DELIBERATELY: hRubyDone is already set, so ServiceMain reports
+ * STOPPED and the dispatcher returns within milliseconds; this join MUST land
+ * so the process never outlives/abandons a live SCM connection (research trap
+ * 13). Bounded-in-practice, documented like phylax's PBKDF2.
+ *
+ * specific_exit: 0 ⇒ clean (NO_ERROR); nonzero ⇒ 1066 ERROR_SERVICE_SPECIFIC_ERROR
+ * with that dwServiceSpecificExitCode. In console mode the dispatcher already
+ * exited (1063), so the join returns immediately and no STOPPED is reported. */
+static VALUE
+host_done(VALUE mod, VALUE vspecific)
+{
+    DWORD specific = NUM2ULONG(vspecific);
+    join_t j;
+    (void)mod;
+
+    EnterCriticalSection(&g_host.lock);
+    if (specific == 0) {
+        g_host.win32_exit    = NO_ERROR;
+        g_host.specific_exit = 0;
+    } else {
+        g_host.win32_exit    = ERROR_SERVICE_SPECIFIC_ERROR; /* 1066 */
+        g_host.specific_exit = specific;
+    }
+    LeaveCriticalSection(&g_host.lock);
+
+    SetEvent(g_host.hRubyDone);
+
+    if (g_host.hDispatcher) {
+        j.h = g_host.hDispatcher;
+        rb_thread_call_without_gvl(join_fn, &j, NULL, NULL);
+        CloseHandle(g_host.hDispatcher);
+        g_host.hDispatcher = NULL;
+    }
+    return Qtrue;
+}
+
+/* ============================================================================
+ *  SCM-client primitives (§4). Each opens and closes every handle within the
+ *  call; nothing outlives it. Handles are closed BEFORE any raise (the
+ *  "nothing owned across a potential raise" invariant). GVL released for the
+ *  LRPC calls (they can stall under the SCM database lock); NULL ubf (RPC is
+ *  not per-thread cancelable; calls are bounded).
+ * ==========================================================================*/
+
+/* ---- argument bundle for _install, marshalled in C before the no-GVL call --*/
+
+typedef struct {
+    WCHAR *name, *display, *binpath, *description, *account, *password;
+    DWORD start_type;       /* SERVICE_AUTO_START | SERVICE_DEMAND_START */
+    int   delayed;          /* delayed-auto flag */
+    int   has_preshutdown;
+    DWORD preshutdown_ms;
+    int   restart;          /* configure failure actions */
+    DWORD restart_delay_ms, reset_secs;
+    int   restart_on_non_crash;
+    /* outputs */
+    DWORD gle;
+    const char *failed_api; /* NULL on success */
+} install_t;
+
+/* Runs WITHOUT the GVL: no Ruby calls inside. All inputs are plain C. */
+static void *
+install_fn(void *p)
+{
+    install_t *a = (install_t *)p;
+    SC_HANDLE scm = NULL, svc = NULL;
+    DWORD desired = SERVICE_CHANGE_CONFIG | SERVICE_START | DELETE;
+
+    a->failed_api = NULL;
+    a->gle = 0;
+
+    scm = OpenSCManagerW(NULL, NULL, SC_MANAGER_CREATE_SERVICE);
+    if (!scm) { a->gle = GetLastError(); a->failed_api = "OpenSCManager"; return NULL; }
+
+    svc = CreateServiceW(scm, a->name, a->display, desired,
+                         SERVICE_WIN32_OWN_PROCESS, a->start_type, SERVICE_ERROR_NORMAL,
+                         a->binpath, NULL, NULL, NULL, a->account, a->password);
+    if (!svc) {
+        a->gle = GetLastError(); a->failed_api = "CreateService";
+        CloseServiceHandle(scm);
+        return NULL;
+    }
+
+    /* Config steps; any failure after creation rolls the service back. */
+    if (a->description) {
+        SERVICE_DESCRIPTIONW d;
+        d.lpDescription = a->description;
+        if (!ChangeServiceConfig2W(svc, SERVICE_CONFIG_DESCRIPTION, &d)) {
+            a->gle = GetLastError(); a->failed_api = "ChangeServiceConfig2(description)"; goto rollback;
+        }
+    }
+    if (a->delayed) {
+        SERVICE_DELAYED_AUTO_START_INFO di;
+        di.fDelayedAutostart = TRUE;
+        if (!ChangeServiceConfig2W(svc, SERVICE_CONFIG_DELAYED_AUTO_START_INFO, &di)) {
+            a->gle = GetLastError(); a->failed_api = "ChangeServiceConfig2(delayed)"; goto rollback;
+        }
+    }
+    if (a->has_preshutdown) {
+        SERVICE_PRESHUTDOWN_INFO pi;
+        pi.dwPreshutdownTimeout = a->preshutdown_ms;
+        if (!ChangeServiceConfig2W(svc, SERVICE_CONFIG_PRESHUTDOWN_INFO, &pi)) {
+            a->gle = GetLastError(); a->failed_api = "ChangeServiceConfig2(preshutdown)"; goto rollback;
+        }
+    }
+    if (a->restart) {
+        SC_ACTION actions[3];
+        SERVICE_FAILURE_ACTIONSW fa;
+        int i;
+        for (i = 0; i < 3; i++) {
+            actions[i].Type  = SC_ACTION_RESTART;
+            actions[i].Delay = a->restart_delay_ms;
+        }
+        memset(&fa, 0, sizeof(fa));
+        fa.dwResetPeriod = a->reset_secs;
+        fa.lpRebootMsg   = NULL;
+        fa.lpCommand     = NULL;
+        fa.cActions      = 3;
+        fa.lpsaActions   = actions;
+        if (!ChangeServiceConfig2W(svc, SERVICE_CONFIG_FAILURE_ACTIONS, &fa)) {
+            a->gle = GetLastError(); a->failed_api = "ChangeServiceConfig2(failure_actions)"; goto rollback;
+        }
+        if (a->restart_on_non_crash) {
+            SERVICE_FAILURE_ACTIONS_FLAG ff;
+            ff.fFailureActionsOnNonCrashFailures = TRUE;
+            if (!ChangeServiceConfig2W(svc, SERVICE_CONFIG_FAILURE_ACTIONS_FLAG, &ff)) {
+                a->gle = GetLastError(); a->failed_api = "ChangeServiceConfig2(failure_flag)"; goto rollback;
+            }
+        }
+    }
+
+    CloseServiceHandle(svc);
+    CloseServiceHandle(scm);
+    return NULL;
+
+rollback:
+    DeleteService(svc); /* best-effort: the create handle holds DELETE */
+    CloseServiceHandle(svc);
+    CloseServiceHandle(scm);
+    return NULL;
+}
+
+/* Winsvc._install(name, display, binpath, description|nil, account|nil,
+ *                 password|nil, start_type, delayed, preshutdown_ms|nil,
+ *                 restart, restart_delay_ms, reset_secs, on_non_crash) -> true */
+static VALUE
+svc_install(int argc, VALUE *argv, VALUE mod)
+{
+    install_t a;
+    VALUE name, display, binpath, description, account, password;
+    VALUE start_type, delayed, preshutdown, restart, rdelay, reset, noncrash;
+    (void)mod;
+
+    if (argc != 13) rb_raise(rb_eArgError, "winsvc: _install expects 13 args, got %d", argc);
+    name        = argv[0];
+    display     = argv[1];
+    binpath     = argv[2];
+    description = argv[3];
+    account     = argv[4];
+    password    = argv[5];
+    start_type  = argv[6];
+    delayed     = argv[7];
+    preshutdown = argv[8];
+    restart     = argv[9];
+    rdelay      = argv[10];
+    reset       = argv[11];
+    noncrash    = argv[12];
+
+    memset(&a, 0, sizeof(a));
+    /* Convert all strings up front (TypeError here owns no handle). */
+    a.name        = to_wide(name);
+    a.display     = to_wide(display);
+    a.binpath     = to_wide(binpath);
+    a.description = NIL_P(description) ? NULL : to_wide(description);
+    a.account     = NIL_P(account)     ? NULL : to_wide(account);
+    a.password    = NIL_P(password)    ? NULL : to_wide(password);
+    a.start_type  = NUM2ULONG(start_type);
+    a.delayed     = RTEST(delayed) ? 1 : 0;
+    a.has_preshutdown = NIL_P(preshutdown) ? 0 : 1;
+    a.preshutdown_ms  = NIL_P(preshutdown) ? 0 : NUM2ULONG(preshutdown);
+    a.restart            = RTEST(restart) ? 1 : 0;
+    a.restart_delay_ms   = NIL_P(rdelay) ? 0 : NUM2ULONG(rdelay);
+    a.reset_secs         = NIL_P(reset)  ? 0 : NUM2ULONG(reset);
+    a.restart_on_non_crash = RTEST(noncrash) ? 1 : 0;
+
+    rb_thread_call_without_gvl(install_fn, &a, NULL, NULL);
+
+    /* Free every wide buffer before any raise. */
+    xfree(a.name); xfree(a.display); xfree(a.binpath);
+    if (a.description) xfree(a.description);
+    if (a.account)     xfree(a.account);
+    if (a.password)    xfree(a.password);
+
+    if (a.failed_api) raise_gle(a.failed_api, a.gle);
+    return Qtrue;
+}
+
+/* ---- _service_state ------------------------------------------------------ */
+
+typedef struct {
+    WCHAR *name;
+    DWORD  state;       /* SERVICE_* current state */
+    DWORD  gle;
+    const char *failed_api;
+} state_t;
+
+static void *
+state_fn(void *p)
+{
+    state_t *a = (state_t *)p;
+    SC_HANDLE scm = NULL, svc = NULL;
+    SERVICE_STATUS_PROCESS ssp;
+    DWORD needed = 0;
+
+    a->failed_api = NULL; a->gle = 0; a->state = 0;
+
+    scm = OpenSCManagerW(NULL, NULL, SC_MANAGER_CONNECT);
+    if (!scm) { a->gle = GetLastError(); a->failed_api = "OpenSCManager"; return NULL; }
+    svc = OpenServiceW(scm, a->name, SERVICE_QUERY_STATUS);
+    if (!svc) { a->gle = GetLastError(); a->failed_api = "OpenService"; CloseServiceHandle(scm); return NULL; }
+
+    if (!QueryServiceStatusEx(svc, SC_STATUS_PROCESS_INFO, (LPBYTE)&ssp,
+                              sizeof(ssp), &needed)) {
+        a->gle = GetLastError(); a->failed_api = "QueryServiceStatusEx";
+    } else {
+        a->state = ssp.dwCurrentState;
+    }
+    CloseServiceHandle(svc);
+    CloseServiceHandle(scm);
+    return NULL;
+}
+
+/* Winsvc._service_state(name) -> Integer (SERVICE_* state). Raises NotFound etc. */
+static VALUE
+svc_service_state(VALUE mod, VALUE name)
+{
+    state_t a;
+    (void)mod;
+    memset(&a, 0, sizeof(a));
+    a.name = to_wide(name);
+    rb_thread_call_without_gvl(state_fn, &a, NULL, NULL);
+    xfree(a.name);
+    if (a.failed_api) raise_gle(a.failed_api, a.gle);
+    return ULONG2NUM(a.state);
+}
+
+/* ---- _control_stop ------------------------------------------------------- */
+
+typedef struct {
+    WCHAR *name;
+    int    result;      /* 0 = sent, 1 = already stopped (1062), 2 = retry (1061) */
+    DWORD  gle;
+    const char *failed_api;
+} ctlstop_t;
+
+static void *
+ctlstop_fn(void *p)
+{
+    ctlstop_t *a = (ctlstop_t *)p;
+    SC_HANDLE scm = NULL, svc = NULL;
+    SERVICE_STATUS ss;
+
+    a->failed_api = NULL; a->gle = 0; a->result = 0;
+
+    scm = OpenSCManagerW(NULL, NULL, SC_MANAGER_CONNECT);
+    if (!scm) { a->gle = GetLastError(); a->failed_api = "OpenSCManager"; return NULL; }
+    svc = OpenServiceW(scm, a->name, SERVICE_STOP);
+    if (!svc) { a->gle = GetLastError(); a->failed_api = "OpenService"; CloseServiceHandle(scm); return NULL; }
+
+    if (!ControlService(svc, SERVICE_CONTROL_STOP, &ss)) {
+        DWORD e = GetLastError();
+        if (e == ERROR_SERVICE_NOT_ACTIVE)            a->result = 1; /* 1062: already stopped */
+        else if (e == ERROR_SERVICE_CANNOT_ACCEPT_CTRL) a->result = 2; /* 1061: pending — retry */
+        else { a->gle = e; a->failed_api = "ControlService"; }
+    }
+    CloseServiceHandle(svc);
+    CloseServiceHandle(scm);
+    return NULL;
+}
+
+/* Winsvc._control_stop(name) -> :sent | :stopped | :retry. Raises on real errors. */
+static VALUE
+svc_control_stop(VALUE mod, VALUE name)
+{
+    ctlstop_t a;
+    (void)mod;
+    memset(&a, 0, sizeof(a));
+    a.name = to_wide(name);
+    rb_thread_call_without_gvl(ctlstop_fn, &a, NULL, NULL);
+    xfree(a.name);
+    if (a.failed_api) raise_gle(a.failed_api, a.gle);
+    if (a.result == 1) return ID2SYM(rb_intern("stopped"));
+    if (a.result == 2) return ID2SYM(rb_intern("retry"));
+    return ID2SYM(rb_intern("sent"));
+}
+
+/* ---- _delete_service ----------------------------------------------------- */
+
+typedef struct {
+    WCHAR *name;
+    DWORD  gle;
+    const char *failed_api;
+} del_t;
+
+static void *
+del_fn(void *p)
+{
+    del_t *a = (del_t *)p;
+    SC_HANDLE scm = NULL, svc = NULL;
+
+    a->failed_api = NULL; a->gle = 0;
+
+    scm = OpenSCManagerW(NULL, NULL, SC_MANAGER_CONNECT);
+    if (!scm) { a->gle = GetLastError(); a->failed_api = "OpenSCManager"; return NULL; }
+    svc = OpenServiceW(scm, a->name, DELETE);
+    if (!svc) { a->gle = GetLastError(); a->failed_api = "OpenService"; CloseServiceHandle(scm); return NULL; }
+    if (!DeleteService(svc)) { a->gle = GetLastError(); a->failed_api = "DeleteService"; }
+    CloseServiceHandle(svc);
+    CloseServiceHandle(scm);
+    return NULL;
+}
+
+/* Winsvc._delete_service(name) -> true. Raises NotFound / MarkedForDelete / etc. */
+static VALUE
+svc_delete_service(VALUE mod, VALUE name)
+{
+    del_t a;
+    (void)mod;
+    memset(&a, 0, sizeof(a));
+    a.name = to_wide(name);
+    rb_thread_call_without_gvl(del_fn, &a, NULL, NULL);
+    xfree(a.name);
+    if (a.failed_api) raise_gle(a.failed_api, a.gle);
+    return Qtrue;
+}
+
+/* ----------------------------------------------------------------- Init --- */
+
+void
+Init_winsvc(void)
+{
+    mWinsvc = rb_define_module("Winsvc");
+
+    eError           = rb_define_class_under(mWinsvc, "Error", rb_eStandardError);
+    eOSError         = rb_define_class_under(mWinsvc, "OSError", eError);
+    eAccessDenied    = rb_define_class_under(mWinsvc, "AccessDenied", eOSError);
+    eExists          = rb_define_class_under(mWinsvc, "Exists", eOSError);
+    eNotFound        = rb_define_class_under(mWinsvc, "NotFound", eOSError);
+    eMarkedForDelete = rb_define_class_under(mWinsvc, "MarkedForDelete", eOSError);
+    eTimeout         = rb_define_class_under(mWinsvc, "TimeoutError", eOSError);
+    eStateError      = rb_define_class_under(mWinsvc, "StateError", eError);
+
+    /* Host bridges (validated by the Ruby layer; hidden via private_class_method). */
+    rb_define_singleton_method(mWinsvc, "_host_start",     host_start,      4);
+    rb_define_singleton_method(mWinsvc, "_host_wait_mode", host_wait_mode,  0);
+    rb_define_singleton_method(mWinsvc, "_host_args",      host_args,       0);
+    rb_define_singleton_method(mWinsvc, "_wait_control",   wait_control,    1);
+    rb_define_singleton_method(mWinsvc, "_inject",         host_inject,     4);
+    rb_define_singleton_method(mWinsvc, "_set_running",    set_running,     0);
+    rb_define_singleton_method(mWinsvc, "_set_paused",     set_paused,      0);
+    rb_define_singleton_method(mWinsvc, "_checkpoint",     checkpoint,      1);
+    rb_define_singleton_method(mWinsvc, "_stop_requested", stop_requested,  0);
+    rb_define_singleton_method(mWinsvc, "_dropped_count",  dropped_count,   0);
+    rb_define_singleton_method(mWinsvc, "_host_done",      host_done,       1);
+
+    /* SCM-client bridges. */
+    rb_define_singleton_method(mWinsvc, "_install",        svc_install,        -1);
+    rb_define_singleton_method(mWinsvc, "_service_state",  svc_service_state,   1);
+    rb_define_singleton_method(mWinsvc, "_control_stop",   svc_control_stop,    1);
+    rb_define_singleton_method(mWinsvc, "_delete_service", svc_delete_service,  1);
+}