Skip to content

XERK-678: Windows follow-ups — archive-raw path separator + tunnel poke guard - #722

Merged
xerhab merged 1 commit into
mainfrom
XERK-678-winfixes
Sep 8, 2026
Merged

XERK-678: Windows follow-ups — archive-raw path separator + tunnel poke guard#722
xerhab merged 1 commit into
mainfrom
XERK-678-winfixes

Conversation

@xerhab

@xerhab xerhab commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

What & why

Two Windows-portability bugs found while driving the native agent on a real Windows host for XERK-678 (both non-fatal — the host runs — but real parity gaps):

#10 — archive-raw path separator (hub-agent.py)

The raw-archive rel-path came from os.path.relpath, which is backslash-separated on Windows, and the hub's safeRawRel splits on / only — so the hub HTTP 400'd every raw sidecar on Windows (archive raw: the hub refused …\tool-results\x.txt … (HTTP 400)). Fix: _session_files normalizes the rel to forward slashes at construction (.replace(os.sep, "/")), and _archivable_rel splits on / so a backslash rel still validates by component. The same normalized rel is the wire key, the archiveRawHave cursor key, and the local reopen path (os.path.join(proj, rel) — Windows accepts / for opens), so one normalization covers all three. No-op on POSIX (os.sep == "/").

#9 — tunnel heartbeat poke (tunnel-agent.js)

pokeHeartbeat did an unguarded process.kill(pid, "SIGUSR1"). On Windows Node that doesn't poke — libuv EINVALs SIGUSR1 or terminates the target — and hub-agent.py installs no SIGUSR1 handler on Windows anyway (already guarded, #719). Fix: pokeHeartbeat returns early on process.platform === "win32" (checked at call time so the suite drives both platforms). The manager beats on its normal TURMA_INTERVAL — the same latency the existing || 1 fallback already accepts.

How verified

  • Both fixes are no-ops on POSIX (confirmed: .replace("/","/") and split("/") are identical to the old else-branch; platform !== "win32" so the poke still fires on Linux).
  • New tests, both mutation-proven to guard their fix:
    • test_archivable_rel_accepts_a_windows_backslash_rel — asserts a forward-slash rel under a mocked Windows os.sep="\\" (the case that actually flows after normalization; True on the fix, False on the bug). Reverting the split fails the test.
    • pokeHeartbeat is a no-op on Windows (tunnel-agent.test.js) — asserts no signal is sent under a mocked win32. Removing the guard fails the test.
  • Full suites green: test_hub_agent.py (2136 OK), node --test tunnel-agent.test.js (116/0).
  • QA: the first qa pass caught that the _archivable_rel test was a placebo (it only asserted backslash rels, where fixed and buggy code agree) — a real find; the test now includes the distinguishing forward-slash-under-Windows-os.sep assertion and is mutation-verified. qa-delta re-confirmation in flight.
  • The real Windows raw-archive round-trip is host-verified (the 400s came from the live host); the fix will be exercised on the next reinstall.

Rules: windows-agent.md (forward-slash-on-the-wire rule), windows-launcher.md (poke now a Windows no-op).

Scope

Follow-up to the merged XERK-678 PRs #719 (manager guards) + #720 (installer). Separate known gap XERK-682 (installer doesn't lay turma-agent-update.ps1 into bin\) is not in this PR.

@xerhab
xerhab merged commit 2b3915d into main Sep 8, 2026
4 checks passed
@xerhab
xerhab deleted the XERK-678-winfixes branch September 8, 2026 16:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant