docs: rojo must run natively on windows; ServerPackages gitignored gotcha
CI / quality (push) Failing after 58s

Two real failures diagnosed 2026-08-06:
- a leftover 'ssh -N -R 34872' reverse tunnel made port 34872 answer as sshd
  while serving the LINUX tree; /api/rojo looked healthy the whole time
- ServerPackages is gitignored, so the windows clone had no wally deps and
  rojo exited on startup, which presents as 'rojo will not connect'
This commit is contained in:
2026-08-06 10:33:36 -04:00
parent 74899a7197
commit 83b3bf80c3
+43
View File
@@ -130,6 +130,49 @@ Two channels, different jobs. **Use [A] to verify what [B] did.**
Full operational detail, version pins, and the failure decoder: **`CLAUDE.md`**.
#### Rojo must run natively on Windows — never over an SSH tunnel
**Rojo runs on the Windows box, in the Windows checkout.** Studio, Rojo and the
repo it serves all live on the same machine. Start it with:
```cmd
cd /d %USERPROFILE%\roblox\tokyo-wangan-racing
%USERPROFILE%\.local\bin\rojo.exe serve default.project.json --port 34872
```
A scheduled task `RojoTWR` does exactly this — `schtasks /Run /TN "RojoTWR"`.
(Launching via `start` over SSH does **not** work: the process dies when the SSH
session exits. Use the task.)
> ⚠️ **Do not reverse-tunnel a Linux Rojo to port 34872.** It was tried
> (`ssh -N -R 34872:127.0.0.1:34872`) and it is actively harmful: the port
> answers, `/api/rojo` returns valid JSON, and everything *looks* healthy — but
> it is serving the **Linux** working tree. Studio then syncs files that are not
> the ones being edited on Windows, and `netstat` shows the port owned by
> **sshd** rather than `rojo`. If port 34872 is owned by anything other than a
> process literally named `rojo`, that is the bug.
>
> Diagnostic that settles it in one line:
> ```powershell
> $l=(netstat -ano | Select-String ":34872.*LISTENING"); (Get-Process -Id (($l[0] -split "\s+")[-1])).ProcessName
> ```
> Expect `rojo`. If you get `sshd`, kill the tunnel.
#### `ServerPackages` is gitignored — Rojo will not start without it
`/Packages/`, `/ServerPackages/` and `wally.lock` are **gitignored**, so a fresh
clone has no dependencies and Rojo **refuses to start**, exiting immediately:
```
[ERROR rojo] Rojo project referred to a file using $path that could not be
turned into a Roblox Instance by Rojo. File $path: ServerPackages
```
That error means *missing Wally deps*, not a broken project file. There is only
one dependency (`ProfileStore`, 19 files / 316 KB). Fix with `wally install`, or
copy the folder from a machine that already has it. **Rojo exiting on startup is
silent from Studio's side — it just looks like Rojo "won't connect."**
### 4b. Reference material on the NAS (1.5 GB, verified present)
Host `unraid-1` (10.10.10.43), reachable over SSH. Base path: