The checked Windows service stop (#7771) is a library of primitives and two operations that
stop a Task Scheduler or WinSW manager, end the wrappers that would relaunch the proxy, and
then confirm the port is free. Every Windows stop path that also restores shared client state
uses it: ocx stop with and without a consent snapshot, ocx uninstall, /api/stop,
ocx service stop / uninstall / remove, service install and backend switch, and the updater.
The best-effort path-token sweep in src/lib/windows-service-wrappers.ts is no longer called by
any stop path. ocx service repair is the one remaining exception: it still stops the manager
through stopWindows() (src/service/repair.ts:259) because it does not restore shared client
state, so the #3008 relaunch window this stop exists to close does not apply to it. Wiring repair
is its own follow-up slice (devlog/_plan/261111_windows_service_stop/060_implementation.md,
"Follow-up slices"). macOS and Linux keep their manager stops and timing; only the signatures
turned async. The design and its slices live in devlog/_plan/261111_windows_service_stop/.
src/service/windows-process-native.ts holds the in-process primitives for Windows x64. It loads
kernel32.dll and advapi32.dll from resolveTrustedWindowsSystemDirectory(), requires bun:ffi
lazily, caches a failed load as unavailable, and closes every handle in a finally:
- creation time through
GetProcessTimes, as epoch milliseconds truncated from the FILETIME; - a checked terminate:
OpenProcess(PROCESS_TERMINATE | PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE), then compare the creation time with the bound value and read the token user on that handle. CallTerminateProcesson the same handle only when the token user SID equals the current process token user SID. The result isterminated,gone,reused(creation mismatch),owner-unverified,deniedorunavailable; - an exit watch: a handle opened at bind time and polled with
WaitForSingleObject(handle, 0); - the Task Scheduler service host PID through
QueryServiceStatusExonSchedule, only while it runs.
Windows ARM64, other platforms and any test that simulates a platform get no native API.
src/service/windows-process-evidence.ts is the facade the operations use. Its process snapshot is
one capped PowerShell snapshot that emits UTF-8 JSON and uses ISO UTC for CreationDate.
It reads owner SIDs for command lines carrying this home's launcher or service script as complete
tokens first, then other wrapper images, unreadable images, and command lines containing the fixed
opencodex-service basename prefix. Owner enrichment admits at most 32 candidates within
1.5 s after enumeration and prioritization, with a 1 s operation timeout on each owner or refresh
call. Every row is retained and skipped owners remain unknown. The refresh is skipped if
the owner query spends the budget. Owner verification requires a successful GetOwnerSid,
valid local/domain or Entra ID SIDs, and a fresh CIM read reporting the original creation time.
Matching SIDs prove the current account. Different supported SIDs prove a foreign account.
Built-in and virtual service SIDs and failed or skipped lookups leave ownership unverified.
Raw SIDs stay within the snapshot parser. Later operations receive nullable foreignOwner.
All reads share the snapshot timeout and output cap. On x64 a native creation time is kept
only when it agrees with CIM within one millisecond. A disagreement clears creation time
and owner evidence. Elsewhere the CIM time is used for observation. The Schedule PID falls
back to a capped sc.exe queryex Schedule from the trusted system directory.
src/service/windows-stop-binding.ts decides, as a pure function over a snapshot, which processes
may be terminated. A process is bound only when its image is wscript.exe, cscript.exe or
cmd.exe; its command line carries this home's launcher VBS or service script path as a complete
token; it is an ancestor of the identity-checked child, a descendant of a bound wrapper, a child
of the Schedule host (SCM PID), or, only while this home's task is registered, an orphan (a parent
that is missing or was created after it); its creation time was read; and its owner SID
was verified as the current user's SID. The proxy child is never a candidate. A wrapper that matches image and path but fails lineage is reported unbound and
left alone. A proven foreign owner is excluded from both bound and unbound candidates, while its
row remains available for ancestry so a live parent cannot be mistaken for an orphan.
Unverified ownership on an otherwise eligible wrapper ends Part A with evidence-unreadable
before mutation. The output directs the operator to the owning session and Task Manager.
A matching wrapper without a creation time or image name, or a wrapper image with no readable
command line under a bound wrapper or above the child while a manager is registered, also
leaves evidence unreadable. Bound wrappers are ordered
deepest first and carry pid, creation time, image and a SHA-256 digest of the command line.
src/service/windows-checked-stop.ts is Part A, stopWindowsServiceChecked(deps, options). Every
external effect is injected. It probes registration (2 s each). An unreadable answer is unknown
with nothing changed. With nothing registered it enumerates once for a stray wrapper of a deleted
task; an unreadable table or no wrapper is absent. With a task registered or a stray sweep
running, it reads the Schedule host PID (2 s). A WinSW-only registration also binds against a
process enumeration, including when WinSW is stopped, so ancestry and stray-wrapper evidence
are checked before a stop can be confirmed. Admission then compares the time left on the
caller's deadline, which already excludes these first steps, with the worst case still to come,
and returns unverified-budget without changing anything when it does not fit. It binds, ends
the task's verified running instances (2 s for proof and stop together) or stops WinSW (a
2 s stop command and an SCM poll capped at <stoptimeout> + 2 s), terminates bound survivors
deepest first, waits on the bind-time watches (terminates and wait share 3 s), and reads the
manager state once (1 s). Denied stops every further step. A cap overrun is unknown. A wrapper or
manager still running is survived (unbound-wrapper when the survivor was never bound). WinSW
is survived while the proxy is still alive after the service reports stopped. The authorizer
variant guardedStopWindowsServiceChecked runs its authorizer at entry, before each manager stop and before each terminate and
reports a refusal as WindowsCheckedStopRefusedError with what had already happened. For Task
Scheduler it reauthorizes after validating the helper proof, before sending stop on stdin. The
helper and outer deadlines must still be open after authorization.
Each step that asks the machine runs under a cap that races a timer and rechecks the elapsed time
on the injected clock. The Scheduler proof-time authorization shares the 2 s task-end cap.
Opening bind-time watches and the other authorization calls have no individual cap. Authorization
before terminating a wrapper spends time from the shared 3 s terminate-and-wait window. Part A has no
overall cap either, so a caller with a tighter bound than the sum of the caps (the /api/stop
route's 4 s sweep and 6 s Part A in 030) needs an outer race or smaller caps.
src/service/windows-stop-confirm.ts is Part B, confirmWindowsStopFreed(deps), run after the caller's
graceful child stop. The port must stay free for a 6 s hold, measured between sample starts,
inside a window of min(12 s, remaining - 0.5 s - 5 s - reserve) with a 6 s floor. A final
enumeration (5 s, sharing its cap with the listener identification) must show no wrapper image
with this home's path token after excluding proven foreign owners. The same exclusion applies
to the unreadable-image check and the guarded manager's candidate checks. Its inspection-only
windowsProcessList shares the owner snapshot and parser but does not expose creation times or
gain terminate authority. An unreadable table is not success. A listener is ours
(survived), foreign (portHeldByForeign) or left by an exited owner, which is not foreign.
resolveWindowsStopPort picks the runtime-port record, then the wrapper's baked port, then the
configured port.
src/service/windows-stop-budget.ts holds the caps and the admission arithmetic. With default
settings the minimum is 48.5 s for a guarded Task Scheduler stop, 56.5 s for a snapshotless one
and 50.5 s for WinSW. Each includes the 0.5 s closing port sample that Part B can take past its
window.
src/service/windows-checked-stop-live.ts is the production side of every seam: capped
asynchronous schtasks and sc.exe calls through execFile (a deadline-derived timeout is
floored to whole milliseconds and one that floors to 0 spawns nothing, because execFile reads 0
as no timeout), the evidence snapshot windowsProcessSnapshot for every bind, the checked
terminate, the exit watch, the Part B port sampler and the listener identity.
src/service/windows-task-instance-stop.ts keeps the root registration and its running instances
in one Task Scheduler COM session. It passes the registered XML and the helper's current account as
base64 UTF-8 to preserve Unicode through the console. The live adapter checks the recognized task
shape, the exact launcher, and the single run-as principal through src/service/windows-taskxml.ts.
Trigger user IDs are checked separately. The stop proof accepts a disabled task with the same
ownership evidence. Installation health still requires an enabled task.
The helper requires a successful same-account SID check for every EnginePID, with the process
creation time re-read after the owner lookup. After approval it re-reads the registration XML and
refreshes every captured instance to verify that its GUID, engine PID and running state still agree.
It stops each captured IRunningTask by instance GUID. An empty collection counts as idle only if
the task is ready or disabled. Failed proof returns evidence-unreadable with instructions to
verify the task in Task Scheduler and stop it from its owning session.
The Scheduler exposes current registration XML separately from instance identity. An instance already running under the same account from an earlier definition can still be visible under that path. Changing the registered definition requires task write access, normally held by the task owner, Administrators and SYSTEM. Those principals can already stop tasks they own or administer. A replacement launched after capture has a separate GUID and cannot be stopped by the captured objects. The final manager-state probe treats both running and queued tasks as active. Task Scheduler permissions Instance stop protocol
The task's running state is read from schtasks /query /fo CSV. The status words observed from shipped zh-CN and
ko-KR resources are recognized there (#8863), because a cold Get-ScheduledTask takes 1.6 s to
4.9 s and cannot finish inside the 1 s cap. Any other localized word still falls back to it.
The instance stop maps an access-denied HRESULT to denied. A running WinSW service is only this home's manager
when sc qc shows a BINARY_PATH_NAME naming this installation's WinSW executable, the same
proof the guarded manager path uses: the service ID is fixed, so a successful sc query alone
would let Part A stop another installation's service. An unreadable registration is unknown
(evidence-unreadable, nothing changed); a foreign executable is reported as nonexistent, so
Part A stops nothing and answers absent.
The port sampler is sampleWindowsStopPort(port, timeoutMs), async and bounded by the caller's
timeout: it runs netstat.exe from the trusted System32 directory through execFile with that
timeout and SIGKILL, and a scan that misses the timeout, or cannot be read, samples unknown.
A synchronous scan would ignore the cap and could stall the stop for the helper's own 5 s. A row
whose owner has exited is cleared like reclaimListenPort does, but only the rows that exited
PID owns: dropWindowsTcpRowsForLocalPort takes an owner filter, so a program that took the port
between scans keeps its connections. The listener identity is
tri-state over inspectOcxStartProcessIdentity: only a positive mismatch is foreign, and an
unverifiable probe (another account's or an elevated process's command line) stays unknown.
verifyPidIdentity's null collapses those two, which would report a listener we merely could not
read as another program holding the port.
src/service/windows-service-stop.ts is what callers call: runWindowsServiceStopPartA (optional
admission, a reused bind snapshot, the updater's authorizer, a hard cap for the route),
confirmWindowsServiceStop (Part B), the mapping onto ServiceStopOutcome (absent, stopped;
survived, denied and unverified-budget are failed; unknown is state-unknown), the additive
serviceStopReason and the receipt record. The deadline lives in
src/service/windows-stop-deadline.ts, and its origin depends on who is stopping. ocx stop
takes --deadline-ms <n>, else OCX_STOP_DEADLINE_MS (empty or invalid counts as absent), else
60 s, measured from the command's own start: that is the operator's budget, and
performance.now() counting from performance.timeOrigin makes it an absolute value on the Part
A clock. Every other caller starts the default 60 s when its stop phase begins, because it
reaches the stop after work it cannot charge to the stop — the scheduler registration and the UAC
prompt — and a budget measured from process start could already be spent, which made admission
refuse unverified-budget a stop that had its whole budget left. The first deadline read in a
stop phase arms it and later reads inside that phase keep it, so one deadline governs the whole
stop instead of sliding forward.
stopServiceIfInstalledReport/stopServiceIfInstalledDetailed(src/service/orchestration.ts) are async and run Part A on Windows. On Windows Task Scheduler never yieldsstopped-respawnable.- Plain
ocx stop(src/cli/stop-windows-checked.ts) admits against the deadline with orphan discovery and the inherited receipts counted. A Part A other than stopped or absent holds the child: no/api/stopPOST, the shared teardown skipped,servicefailed or state-unknown,proxyunknown. A thrown Part A also holds the child and reports a service error. After a stopped Part A, the POST skipsstopProxy's legacy 15 swaitForStoppedPort, orphan discovery is capped at 3 s, and Part B replaces the respawn re-poll: our identity back on the port isproxy: respawned, an unconfirmed port isevidence-unreadable, and another program on the port setsportHeldByForeignwithout failing the stop. The port wait is skipped on BOTH Windows paths, guarded included, throughwindowsPartBOwnsPortWait;windowsPartBDuestays snapshotless-only because it also gates the legacy respawn re-poll. A failed owner receipt claim refuses the child stop and shared teardown on both paths.ocx uninstall's twostopProxycalls pass the same predicate. - The guarded path reads the evidence snapshot and the Schedule host PID once per inspection;
stopManagerbinds on the revalidation's snapshot (so its admission does not count a second enumeration), Part B runs aftersettleon the approved endpoint, and the manager-state checks reuse Part B's final enumeration. - A registered task whose state is
not-runningpromotes its surviving wrappers tobound-strayonly afterwinTaskXmlandwinRegistrationOurspass (src/service/windows-guarded-manager.ts). The state word says the task is inert, not that it is ours; promoting on the word alone let a same-named foreign task make this home's hand-started wrappers terminable. Nothing surviving keeps theabsentverdict without the read; an unreadable definition isevidence-unreadableand a definition that is not this installation's isunknown, both leaving the previous verdict. - The teardown receipt carries the Part A record (
partAstopped or absent, the registered managers, the ended wrappers as pid + creation time): written at the claim, or added by the owner for a receipt claimed before Part A./api/stop(src/server/stop-service-route.ts) skips its own Part A only for a record whose managers are still the registered ones; a receipt without it runs Part A capped at 6 s; without a receipt a registered WinSW keeps its in-process stop and anything else gets the stray sweep capped at 4 s. A cap overrun isservice_state_unknown, and the manager commands and terminates are gated off once the cap has passed. ocx service stop(src/service/cli-windows-stop.ts) refuses on a Part A other than stopped or absent, claims a teardown receipt before the deferred tracked-proxy stop when this home owns the shared teardown (a failed claim sends no child stop), runs Part B, and clears the receipt only after the restore. With Part A absent it requires every candidate endpoint to be definitively dead; live or unknown keeps the receipt and blocks restoration.ocx service uninstall/removerefuse before deleting the task unless Part A stopped (or found nothing) and Part B did not find our identity or an unreadable port. Removal claims the same receipt, carrying Part A's record, before its child stop: Part A leaves the scheduler task registered, so a receipt-less POST answersrespawnable_service(409) and the removal refuses with the proxy left running. The receipt is discharged only after the shared restore, and a failed claim sends no child stop. Part Aabsentsays no manager is registered, not that nothing serves, so removal then proves every candidate endpoint (endpointsToProve(readRuntimePort(), loadConfig()), the setocx uninstallproves) tri-state: only a definitive dead on all of them permits deleting the task, while live or unknown refuses and keeps the receipt. The receipt endpoint alone is not enough — a stale runtime record naming a closed port must not stand in for the configured port where a live listener can sit.- Every tracked-proxy stop takes its orphan-discovery cap from the caller
(
TrackedProxyStopIo.orphanDiscoveryCapMs). The checked Windows callers pass the admitted 3 s (WINDOWS_STOP_CAPS.orphanDiscovery), which is what admission priced; the omitted default stays the legacy 7 s so macOS and Linux timing is unchanged. - Windows service stop, removal and install resolve one tracked or discovered proxy target before claiming its receipt. The receipt and POST use that target's exact endpoint; Part B checks its port. No target means no receipt or POST. An owning caller refuses a target without an endpoint.
ocx uninstall(src/cli/uninstall-stop.ts) resolves its stop target before it claims anything: the tracked pid with its own runtime endpoint, or the discovered live proxy with the endpoint discovery found it on. The receipt andstopProxythen name the same endpoint, so a stale runtime record cannot produce a receipt for a port the stop never contacted, and no target means no receipt at all (a guessed obligation recovery cannot resolve is worse than none). The tracked record is removed only for a stop that was proven, and the step reports a change only when state changed. When Part A did not end stopped or absent the graceful POST still goes out withallowForcedFallback: false, and that unconfirmed wait is observational: it samples the port withoutreclaimListenPort's kill eligibility, so a forbidden fallback cannot kill through the reclaim path either. An unconfirmed stop is not proof the proxy is down:stopProxyanswers false without contacting the endpoint when the tracked pid is already dead, so the step then requires the tri-stateendpointProvenDown()over every candidate before it reportsprovenDown, exactly as the discovery path does. A different proxy on the configured port would otherwise be missed and shared config restored under it (#3008).ocx uninstallremoves the Windows manager only after a Part A that ended stopped or absent (serviceRemovalAllowedinsrc/cli/uninstall-plan.ts); otherwise the step recordsfailedand leaves the registration, asocx service uninstallrefuses.uninstallServiceDetailed(src/service/orchestration.ts) reads the scheduler probe, the native status andsc qcBINARY_PATH_NAMEbefore the first destructive step: a registration naming another installation's WinSW executable is left untouched, and an unreadable status or ownership refuses and keeps install state. The task used to be deleted first, so an unreadablesc qcleft a half-removed install with no task to retry from. Non-Windows removal is unchanged.prepareServiceInstallrefuses before replacing anything on a Part A other than stopped or absent and stops install and switch on any Part B result other than a free port, naming the owner.ocx uninstallruns Part B as its respawn window after a stopped Part A.- Install and backend switch claim a teardown receipt before their tracked stop when Part A
ended
stopped: the task is still registered, so a receipt-less POST answers 409respawnable_serviceand the install aborted while the old proxy kept serving. The receipt carries Part A's record and its nonce travels on the POST. An install replaces the proxy, so shared config stays pointed at OpenCodex and the receipt is cleared only after the new service is installed and started; an install that fails after the stop keeps it for the nextocx stop. A failed claim sends no child stop. - With Part A
absent, install preparation skips Part B, and the tracked stop can return"none"after its orphan-discovery cap while an unresponsive proxy still holds the port. The candidate set is resolved before cleanup and every endpoint must be definitively dead before the install callback runs; live or unknown throws like a Part B failure. - The updater (
src/update/job-windows-restart.ts) usesguardedStopWindowsCheckedfor both backends, with the service mutation gate as the authorizer. Each of the three call sites insrc/update/job.tsaborts the restart unless the outcome is stopped or absent.
The binding rule excludes the stopping process but not its ancestors. A stop that runs beneath a
wrapper carrying this home's launcher or service-script path would end its own supervision chain,
so runWindowsServiceStopPartA refuses such a stop with nothing changed (unknown, "runs under
this home's service wrapper") by checking the bind snapshot's ancestry of the current PID. Two
callers opt out on purpose: /api/stop runs inside the wrapped proxy, and the updater's worker
descends from the service-run proxy; both exist to end that wrapper, and ending an ancestor never
ends the stopper. Every interactive caller (ocx stop, ocx uninstall, ocx service
commands, install and switch) refuses.
The terminate primitive requires a native process handle. On ARM64, or if the native API
cannot load on x64, terminateWindowsProcessBound returns unavailable without spawning a
helper. If the manager stop leaves a wrapper running or its exit cannot be confirmed, Part A
returns unknown / evidence-unreadable. The operator can check the wrapper from its owning
session in Task Manager, stop it if it is still running, then retry.
tests/windows/windows-stop-binding.test.ts, tests/windows/windows-checked-stop.test.ts,
tests/windows/windows-stop-confirm.test.ts and tests/windows/windows-process-evidence.test.ts
use injected deps, a virtual clock and simulated platforms. The owner-budget and Scheduler stop
script tests run PowerShell against stubbed CIM and COM objects. Live CIM and FFI tests require
Windows and the FFI cases require x64.
The callers are covered by tests/windows/windows-checked-stop-live.test.ts (adapters, ARM64
strict, whole-millisecond timeouts, the ancestry check, the bounded port sampler and the tri-state
listener identity), tests/windows/windows-service-stop-wiring.test.ts
(the real Part A through the wiring: the own-wrapper refusal, the cap, admission, the deadline's
two origins and the receipt record), tests/windows/windows-stop-callers.test.ts (the route, the
service commands, the guarded order, bound-stray, the orphan-discovery cap and the bind on the
evidence snapshot), tests/windows/windows-guarded-manager.test.ts (the not-running promotion
behind its registration proof) and tests/windows/windows-stop-ocx-stop.test.ts (plain ocx stop
through the real CLI with the platform simulated).