midi-harbor/specs/013-windows-support/research.md

# Research: Windows support

**Feature**: 013-windows-support | **Date**: 2026-09-26

Numbered after the original specification's research, whose last entry was R-082, so every R number in the
project names one entry. Findings marked **VERIFIED** were measured on the Windows test machine:
Windows 11 Pro 25H2 (build 26200) in a virtual machine, with rtpMIDI 1.1.14 and teVirtualMIDI 1.3.0.43,
reached over ssh as a standard administrator account and cross-compiled for from macOS.

---

## R-083: Task Scheduler does not restart a program that fails

**Status**: **VERIFIED** (2026-09-26).

**Decision**: The logon task runs `midi-harbor daemon --supervise`, which runs the daemon as a
child and starts it again after a failure: after 2 s, doubling while failures come less than a
minute apart, up to 60 s. A successful exit, which is what a daemon asked to stop returns, ends
supervision.

**Evidence**: A task with `RestartOnFailure` set to every minute, three times, ran
`cmd /c exit 3`. Task Scheduler recorded last result 3 and never ran it again. The setting covers
a task that fails to start, not a program that exits with an error.

**Rejected**: A trigger repeating every minute with `IgnoreNew`. It restarts after up to a minute
instead of two seconds, and it would start again a daemon the user had stopped.

**Also decided**: The task runs as the user with an interactive token and least privilege, so a
standard user can install it and the daemon runs in the user's session, where MIDI devices and
teVirtualMIDI ports are. A Windows service would run in session 0 and needs an administrator. The
command is `conhost.exe --headless`, so the console program opens no window at logon. The
priority is 4, Task Scheduler's normal; its default, 7, is below normal.

## R-084: The DNS Client service's DNS-SD and instance names

**Status**: **VERIFIED** (2026-09-26), with a capture on the Arch VM on the same subnet.

**Decision**: Advertise through `DnsServiceRegister`, looked up in `dnsapi.dll` at run time. A dot
in a session's name is sent as a hyphen.

**Evidence**: Registered with no addresses, the service answers with the host's own and keeps
answering: `avahi-browse -r` on the Arch VM resolved `WinHarbor` to `192.0.2.47:58332`, and the
records went out with goodbyes when the daemon stopped. A name with a dot, escaped as DNS-SD
defines, went out as two labels, `Win Harbor\` (eleven bytes, the backslash kept) and `Test`,
and no browser listed it. A name with any character outside ASCII is lowercased: `Café Test` was
announced as `café test`, while `WinHarbor` kept its case. So the dot's stand-in is ASCII; a
lookalike dot lowercased the whole name. This daemon recognises its own records by address and
port, so the changed name does not make it list itself.

**Consequence**: A session whose name holds non-ASCII characters is advertised lowercased on
Windows. Nothing breaks; the name looks different on other machines.

**Browsing** through `mdns-sd` works on Windows as elsewhere: a Windows daemon found a Linux
daemon's port and resolved it.

## R-085: Windows makes a socket on `[::]` IPv6-only

**Status**: **VERIFIED** (2026-09-26). Fixed.

Every invitation a Windows daemon sent to an IPv4 peer failed with "the requested address is not
valid in its context" (10049), and the session waited for a network that was there. Linux and
macOS make a socket bound to the unspecified IPv6 address dual-stack; Windows sets `IPV6_V6ONLY`
by default. The session sockets now clear it explicitly through `socket2`. The existing test that
sends to an IPv4 peer fails on Windows without the change. With it, a Windows daemon joined a
Linux daemon's session at 1.0 ms latency.

## R-086: teVirtualMIDI and WinMM under churn

**Status**: **VERIFIED** (2026-09-26), by PowerShell probes against the driver and by the Windows
integration tests.

- **A slot reused at once keeps its old name.** Closing a port and creating another under a new
  name straight away left WinMM showing the old name, in every process, on six of ten tries, for
  at least five seconds. Created while the old port was still open, the new port showed its own
  name within 28 to 54 ms on ten of ten. With half a second or more between the close and the
  create, the new port always appeared. Renaming in the daemon is a destroy and a create, so the
  backend retires a destroyed port and closes it once the next port exists or after a second.
  With retirement off, the eight-rename test failed five runs of five, on the first rename each
  time; with it, it passed five of five.
- **A closed port lingers.** WinMM often lists a closed port, under its old name or as
  `(unavailable)`, until the driver's next change, in fresh processes too; this is the driver,
  not a cache in one process. The backend keeps names of ports it closed out of its device list
  for up to a minute, and never offers `(unavailable)` application ports.
- **The halves of one port are listed separately.** A new port's input can be listed before its
  output, and each can carry a different `tevmidiN` slot number. Application ports are therefore
  identified by name, which the driver keeps unique.
- **A name already taken** is refused with `ERROR_ALIAS_EXISTS` (1379) by driver 1.3.0.43, not
  the `ERROR_ALREADY_EXISTS` its header suggests. Both are reported as a naming conflict.
- **The first message after another application opens a port can be lost.** In four of
  thirteen runs of the suite, one note sent a few milliseconds after the open arrived only when
  sent again. The tests send until heard and report how many sends it took.
- **Positions move.** WinMM opens by position, and a port closing while another is opened shifted
  the list under the open: a handle once opened a closing port and failed with "undefined
  external error". The backend reads the lists until two readings agree, checks each opened
  handle's own position against what was meant, and retries.

**Timing**: a new port appeared in WinMM 30 to 390 ms after creation.

## R-087: The control channel on Windows

**Status**: **VERIFIED** (2026-09-26).

**Decision**: A named pipe with a random name, `\\.\pipe\midi-harbor-<uuid>`, which refuses
remote clients. The daemon creates it before recording its name in a file at the socket path,
in the user's temporary directory, and clients read the name from there. A record naming anything
but one of our pipes is not followed.

**Rationale**: Tokio has no AF_UNIX on Windows. A fixed pipe name could be created first by
another local user, who would then receive every command the CLI sent. A random name recorded in
a file only the user can read keeps a file permission as the gate, as the socket's mode is on
Unix. The pipe's default access lets other users open it only for reading, which is not enough
to send a request.

**Stopping**: Windows has no terminate signal to send. The daemon waits on an event named
`Local\midi-harbor-<uuid>-stop`, in the session's namespace, and `service stop` sets it, so the
daemon silences held notes and ends sessions before exiting. Ending the task instead is the last
resort after five seconds. Verified: `service stop` against a running daemon logged
"daemon stopped" after its shutdown path.

## R-088: Windows lets a dual-stack socket share its port

**Status**: **VERIFIED** (2026-09-26). Fixed.

The daemon's session tests failed on Windows: a switched-off session's port read as free while
the session still held it. Probed from Rust on the test machine, with a dual-stack `socket2`
socket bound, a plain IPv4 socket and a plain IPv6 socket could each bind the same port; a
second IPv4 socket on an IPv4 socket's port was refused; and a dual-stack socket bound a port an
IPv4 socket already held. Any program could take a session's datagrams. With
`SO_EXCLUSIVEADDRUSE` set before binding, the other binds were refused with 10013, and the
exclusive socket was refused a port held by either family with 10048. Session sockets set it on
Windows. It is the Windows form of the sharing R-080 found on macOS.

## R-089: Cross-compiling and testing

**Status**: **VERIFIED** (2026-09-26).

`x86_64-pc-windows-gnu` with Homebrew's `mingw-w64` builds the whole workspace, the libcosmic
interface included, on the development Mac. `zeroconf` does not build for Windows, since it wants
Apple's Bonjour SDK, so it moved behind the platform crate's responder module.

Test binaries are built with `cargo test --no-run` and run on the test machine by
`scripts/windows-test.sh`. Tests that find the binary or the sources through paths compiled in on
the Mac, `CARGO_BIN_EXE_midi-harbor` and `CARGO_MANIFEST_DIR`, read them from the root of the
current drive on Windows, so the script mirrors the tree under `C:\mh-win\root` and runs the tests
from a drive substituted onto it.

The interface cross-builds at the pinned libcosmic revision `87ab8179` without the `accesskit`
override the owner's notes (`veris/docs/libcosmic.md`) need for newer libcosmic, and it rendered on
the test machine: the Endpoints page listed the daemon's ports. The executable is a console program,
so the interface releases a console only it is attached to, which closes the empty window Windows
otherwise opens beside it.

## R-090: A daemon that did not finish exiting

**Status**: **CLOSED** (2026-09-26). Mitigated.

A daemon run as the service for 27 minutes, with a teVirtualMIDI port, the software synthesiser
open, and a session whose peer had just left, logged "daemon stopped" on `service stop` and never
exited. One thread remained, using no CPU; `taskkill /F` and `Stop-Process -Force` both failed,
and it still held its executable open. A process that cannot be killed is waiting in kernel mode,
so a driver's cleanup at process exit is the likely place. It no longer held a teVirtualMIDI port.

Fifteen start and stop cycles since, from the service and from a shell, with and without a
virtual port and the synthesiser open, all exited. The daemon now closes every
port and device it holds after ending its sessions, before returning, so no driver's close runs in
the process's teardown. Whether that removes the cause is unknown until it recurs or does not.

## R-091: Moving a network port without stopping it first

**Status**: **CLOSED** (2026-09-26). Fixed in T230.

`a_udp_port_that_cannot_be_bound_leaves_the_network_port_where_it_was` failed in two of the Linux
gate runs, the network port found on a third pair after a refused move was undone. It passed in
71 isolated runs, and in three full runs each of this branch and of the commit before it. Moving
a port stopped it, tried the new pair, and on finding it taken started it again on the old one; a
daemon starting beside it in the same test process could hold the old pair for longer than the
bind waits (R-082). The new pair is now bound and released before the port is touched, so a
taken pair is refused while the port still runs where it was, and the test checks the port was
never restarted.

## R-092: Windows Defender Firewall

**Status**: **VERIFIED** (2026-09-26).

Windows asked whether to allow `midi-harbor` on public and private networks the first time the
daemon opened a network port, with the test machine's network marked Public. Sessions the Windows
daemon started worked before any answer. Once the owner allowed it, a Linux daemon invited the
Windows port by address and joined at 0.9 ms. The rules Windows makes are for one program path: a
copy at another path, `C:\mh-win\bin\midi-harbor.exe`, was prompted for again, and ended with
block rules when the prompt went unanswered.

## R-093: Windows MIDI Services

**Status**: **VERIFIED** (2026-09-26) through the App SDK; the in-box API awaits Windows'
late-2026 update.

Windows MIDI Services has two forms of its API over one service. `Windows.Devices.Midi2` is part
of Windows from the update Microsoft's repository says ships starting the last week of November
2026. Its preview packages are for development only. The App SDK,
`Microsoft.Windows.Devices.Midi2`, RC4 1.0.17-rc.4.25, which upstream now labels old, works with
the service Windows already has (10.0.26100.7705 on the test machine) once the user installs the
"Windows MIDI Services SDK Runtime and Tools". A program reaches it through the COM class
`MidiClientInitializer`, created first and kept. The backend uses the in-box API whenever Windows
registers `Windows.Devices.Midi2.MidiSession` under `ActivatableClassId`, and the App SDK
otherwise. It asks the registry rather than activating the class: the preview API copied beside
the program activated on today's Windows, and `CreateVirtualDevice` through it never returned.

- **Session 0.** A virtual device created from an SSH session is never answered. From the
  desktop session, run as an interactive scheduled task, the same code creates it at once. The
  daemon runs at logon in the desktop session; the integration tests have to be started there.
- **The identifier.** The service refused a product instance identifier containing spaces, with
  status 808. It takes ASCII letters, digits, `-` and `_`, 32 at most, so the port's name is
  hashed: `mh-` and sixteen hex digits of its 64-bit FNV-1a. A second device of the same name has
  the same identifier and is refused with no object and no error code, which the bindings report
  as "The operation completed successfully"; the backend refuses a name its own port already
  shows before asking.
- **Receiving.** A port sends as soon as its connection opens, but receives nothing until the
  device is added to the connection as a message processing plugin, as Microsoft's sample does.
- **Naming.** Through RC4 against today's service, a port of two connectors appeared in WinMM as
  "Harbor Split 8640" and "Harbor Split 8640 Gr 2". The service ignored the function block names
  and fell back to naming by group. Upstream's current source calls that fallback a last chance
  that should not be seen in production. The backend recognises its own ports under either
  naming.
- **Closing.** `DisconnectEndpointConnection` never returns, and from then on the service
  answers nothing: the next `CreateVirtualDevice` waited for good. This is Microsoft's issue
  #1236, a duplicate of #1047, fixed for the late-2026 update. Keeping the device object until
  after the disconnect, as the sample does, changed nothing. Ending MidiSrv and starting the
  service recovered it every time. So every call into the service runs on a thread of its own and
  is waited for 5 s. A call that outlives that wait is left running and counted. While any is,
  opening a session or creating a port is refused at once, and virtual ports are reported
  unavailable, naming the service to restart. With all seven integration tests in one process,
  the first passed, its close was given up after 5 s, and the other six were refused within the
  same run of 7.4 s, none waiting on the service.
- **Starting.** Opening a session on a service that had just been stopped took more than 5 s once,
  and was refused. Opening a session is waited for 30 s.

With the service restarted before each, six of the seven integration tests passed: MIDI and a
system-exclusive dump both ways, own ports kept out of the device list, two connectors in the
right directions, a taken name refused, another application's port announced. The rename test
closes a port and creates another, which today's service cannot do.

## Notes

- **Distributing the Windows build.** The teVirtualMIDI SDK page (2026-09-26) says: "Software
  linking to this SDK MAY NOT BE DISTRIBUTED in any way without prior clearance with me (Tobias
  Erichsen)", and offers the MSI module that installs the driver to licensees only. Clearance is
  requested at info@tobias-erichsen.de. Midi Harbor no longer uses it: virtual ports go through
  Windows MIDI Services (R-093).
- **USB hardware exclusivity.** WinMM gave the synthesiser and teVirtualMIDI ports to two
  processes at once on the test machine. The daemon opens every present device, as it does on
  the other platforms; if a Windows release opens USB MIDI devices exclusively, the daemon would
  keep other applications from them.