From e82d841d66f0c2050ddc674c3bc7df8a29c4d424 Mon Sep 17 00:00:00 2001 From: Joseph Mearman Date: Sun, 13 Sep 2026 07:11:39 +0100 Subject: [PATCH] fix(sea): drop windows from the release matrix, a real platform incompatibility MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both windows-latest and windows-11-arm built a working .exe and then crashed silently before printing anything at all when the smoke step ran it. Root cause is a genuine, documented Node.js limitation, not a CI misconfiguration: Node's net module has no real AF_UNIX support on Windows (nodejs/node#55979, nodejs/node#35008) — its local domain there is implemented with named pipes, which must live under \\.\pipe\, never an arbitrary filesystem path. Claude Code's own peer protocol addresses sockets by filesystem path end to end (docs/PROTOCOL.md), so CcPeer.start()'s UDS listen() call cannot succeed on Windows at all. Shipping a Windows binary would only hand users an executable that can never open its own socket. The originally approved plan for the SEA milestone scoped this matrix to darwin and linux only; win32 was added afterward without checking this — it should not have been there in the first place. Reverting to the four platforms that can actually run this software, and documenting the limitation in the README rather than leaving it to be rediscovered as a support question. --- .github/workflows/ci.yml | 4 +--- README.md | 1 + 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 00eb062..c838789 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -107,14 +107,12 @@ jobs: strategy: fail-fast: false matrix: - # Every (platform, arch) pair on a standard runner image: two darwin legs, two linux, two win32 — build-sea.ts qualifies each asset name by process.platform AND process.arch so shared-OS legs cannot clobber each other's release upload, and gives win32 its .exe. + # darwin and linux only, two architectures each: win32 is deliberately excluded. Node's net module has no real AF_UNIX support on Windows — its own docs state the local domain there is implemented with named pipes, which must live under \\.\pipe\ or \\?\pipe\, not an arbitrary filesystem path (see nodejs/node#55979, nodejs/node#35008). Claude Code's own peer protocol is filesystem-path UDS end to end (this repo's own docs/PROTOCOL.md), so CcPeer.start() cannot bind a listening socket on Windows at all — confirmed directly: a windows-latest and a windows-11-arm leg both built a working .exe, then crashed before printing anything at all when the smoke step ran it, because the UDS listen() call itself fails. Shipping a Windows binary would only hand users something that cannot ever open its own socket. build-sea.ts still accepts win32 as a target for anyone building locally on Windows themselves; only the CI/release matrix excludes it. include: - os: macos-latest - os: macos-13 - os: ubuntu-latest - os: ubuntu-24.04-arm - - os: windows-latest - - os: windows-11-arm runs-on: ${{ matrix.os }} timeout-minutes: 20 permissions: diff --git a/README.md b/README.md index 764e78b..96eeb22 100644 --- a/README.md +++ b/README.md @@ -61,5 +61,6 @@ The REST facade (`npx cc-peer`) serves `GET /sessions`, `POST /messages`, `POST - **Same-process constraint**: receipts and idle notices only reach the process that owns the peer's listening socket (the protocol verifies return addresses via kernel peer-pids). Do not split `CcPeer` listening and sending across processes or differently-owned workers. - **Single machine**: the local protocol is Unix-socket only. Writing to cloud sessions directly is blocked by design (device-attestation-signed events); bridged sessions reachable locally still work via their local mirror. +- **No native Windows support**: Claude Code's own peer protocol addresses sockets by filesystem path end to end, but Node's `net` module has no real AF_UNIX support on Windows — its local domain there is implemented with named pipes, which must live under `\\.\pipe\`, not an arbitrary path (see [nodejs/node#55979](https://github.com/nodejs/node/issues/55979)). `CcPeer.start()` cannot bind a listening socket on Windows as a result. The SEA release matrix builds darwin and linux only for this reason; running from source or `npx` on Windows hits the same limitation. - **File transfers to Claude sessions** wait on an upstream feature flag (`tengu_send_file`) before Claude-side materialisation activates; peer-to-peer transfers work today. - Verified against Claude Code 2.1.269; treat every Claude Code upgrade as a potential protocol change.