[10/36] Add OC-020 WebSocket support

[cjohnsto-nz]

Scope and stack-integrity note

This PR remains the OC-020 WebSocket fixture and baseline support branch at 87caf31.

The review-only transport failure tests originally committed here as 5177b78 are preserved at the stack tip in PR #72 as 3861f90. The full 37-PR sequential composition audit showed that keeping 5177b78 on this historical branch conflicts at PR #51, so this branch was restored to its original implementation head instead of forcing that conflict through the descendants.

Validation:

• PR [09/36] Add OC-010 GraphQL support #43 -> PR [10/36] Add OC-020 WebSocket support #44: clean
• PR [10/36] Add OC-020 WebSocket support #44 -> PR [11/36] Record OC-010 through OC-040 supervisor audit #45: clean
• final WebSocket suite: 29/29
• all 37 live branch heads compose sequentially without conflicts
• GitHub: MERGEABLE / CLEAN --- This is **part 12 of 21 in a stack** made with GitButler: -  21  [22/36] Release 0.8.0 with packaged PDF.js preview #54 -  20  [21/36] Complete OC-070 protocol surface polish #56 -  19  [20/36] Record final OpenCollection supervisor acceptance #53 -  18  [19/36] Add OC-110 runtime authoring UX #52 -  17  [18/36] Add OC-080 runtime lifecycle and OC-110 task setup #51 -  16  [16/36] Record OC-050 OC-090 OC-100 supervisor audit #50 -  15  [15/36] Add OC-050 auth and transport support #49 -  14  [14/36] Add OC-100 request type UX #48 -  13  [13/36] Add OC-100 request type UX task #47 -  12  [12/36] Add OC-080 and OC-090 task tracks #46 -  11  [11/36] Record OC-010 through OC-040 supervisor audit #45 -  10  [10/36] Add OC-020 WebSocket support #44 <-- current -  9  [09/36] Add OC-010 GraphQL support #43 -  8  [08/36] Require demo server fixtures for parallel tracks #42 -  7  [07/36] Record OC-000 and OC-060 supervisor audit #41 -  6  [06/36] Add OC-060 schema round-trip validation #40 -  5  [05/36] Add OC-040 runtime scripting support #39 -  4  [04/36] Add OC-090 gRPC streaming support #38 -  3  [03/36] Add OC-030 gRPC unary protobuf support #37 -  2  [02/36] Add OC-000 protocol dispatch foundation #36 -  1  [01/36] Add OpenCollection agent plan #35

[APKiwi]

Verdict: approve with nits, as a test-and-fixtures increment. Which is what this actually is:

• Major, labeling: the increment contains no implementation. base..head is exactly test/webSocketSupport.test.ts plus six demo fixtures. webSocketClient.ts, the panel/service/CodeLens wiring and the ws dep all live in ancestor branches, so a reviewer reading this diff can't review connect races, socket cleanup or auth where the title claims they land. I checked the implementation out-of-band: the settle guard is idempotent, _onPanelDisposed does disconnect and terminate, activeConnectionCount bookkeeping is right, rejectUnauthorized defaults true. Sound code, wrong PR.
• Minor: the fixture server implements upgrade rejection (401 route, auth route) and a rejected-upgrade demo exists, but no test asserts client behavior on a server-side upgrade rejection. The only negative test is the pre-connect URL-scheme guard.
• Minor: makeEnvService injects the test's own interpolate/interpolateJson reimplementations, so the JSON-variant assertions validate the mock's coercion, not production EnvironmentService. A divergence would still pass.
• Minor: no wss:// + rejectUnauthorized coverage, the one security-relevant knob is untested.
• Nit: auth headers ride the upgrade request in plaintext over ws://, expected for a dev tool, noting there's no downgrade warning.

Tests otherwise: good, 13 deterministic tests covering connect/echo, frame types, variants, auth, cancellation via a real hold route, cleanup assertions across lifecycle paths.

Deps: none in this increment. For the record ws@8.21 has zero hard dependencies, the lean standard choice, nothing heavier rode along.

[cjohnsto-nz]

Fixed in 5177b78.

The three actionable test gaps are now closed:

• Added a direct WebSocket client test for an HTTP 401 upgrade rejection and verified the active-connection registry is empty afterward.
• Removed the test-only interpolation reimplementation. The suite now uses the production EnvironmentService, stubbing only variable resolution.
• Added a real local wss:// fixture with a self-signed certificate. The tests prove that certificate verification is enforced by default and that missio.tls.rejectUnauthorized=false permits the connection.

Not changing the proposed credential warning for ws://. OC-020 explicitly supports both ws:// and wss://, and the local development fixture intentionally uses ws://. A warning would be new product behaviour, not a missing part of this task's transport contract. Authentication interpolation and handshake headers remain covered by the branch's tests.

The apparent implementation/PR split is a consequence of concurrent work in the stack, not missing WebSocket implementation. src/services/webSocketClient.ts was introduced in 45e5800 on PR #39 (feature/oc-040-runtime-scripting-testing), while protocol dispatch and shared UI/extension wiring were already present in ancestor commits. This PR owns the OC-020 demo fixtures and end-to-end acceptance coverage. Re-homing those ancestor hunks now would rewrite lower stack history and create avoidable conflicts without changing the delivered code.

Validation completed against this PR merged onto the current PR #43 base: TypeScript compile, production build, 390/390 tests, and 35/35 demo collection files. GitHub's build and security checks are green. I also ran the mandatory three-way stack-edge check, and immediate child PR #45 remains MERGEABLE/CLEAN after this push.

[cjohnsto-nz]

Correction to my earlier review response:

The transport-failure coverage in 5177b78 is valid, but the complete 37-PR sequential audit showed that keeping it on PR #44 creates a conflict when the stack reaches PR #51. I therefore restored this branch to its implementation head 87caf31 and preserved the tests at the stack tip in PR #72 as 3861f90.

This is a relocation, not a dropped fix. The final composite runs the WebSocket suite 29/29, both adjacent edges (#43 -> #44 and #44 -> #45) are clean, and GitHub reports this PR MERGEABLE / CLEAN with all checks passing.