From 25d1e37750c8e7b2fa20e652aa0abfc5ff2b2516 Mon Sep 17 00:00:00 2001
From: jesse <jesse@devlabhq.net>
Date: Thu, 6 Aug 2026 21:59:48 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20rojo=20watchdog=20(RojoTWR-Guard)=20?=
 =?UTF-8?q?=E2=80=94=20rojo=20does=20not=20stay=20up=20on=20its=20own?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified by killing rojo and confirming the guard restored it with 34872
owned by 'rojo'. Guard refuses to start if the port is held by anything
else (sshd tunnel) rather than masking that bug.
---
 PROJECT-BRIEF.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/PROJECT-BRIEF.md b/PROJECT-BRIEF.md
index 36e1716..5fd3429 100644
--- a/PROJECT-BRIEF.md
+++ b/PROJECT-BRIEF.md
@@ -144,6 +144,32 @@ 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.)
 
+**Rojo does not stay up on its own.** It was observed dying repeatedly (Studio
+restarts, machine sleep, the one-shot task simply ending). A watchdog handles
+this now:
+
+```
+%USERPROFILE%\rojo-guard.ps1          idempotent restart script
+schtasks /Query /TN "RojoTWR-Guard"   runs it every 3 minutes
+%USERPROFILE%\rojo-guard.log          only logs real events, silent when healthy
+```
+
+The guard is deliberately conservative:
+- if `rojo` already owns 34872 it exits 0 and does nothing (safe mid-session —
+  it will not disturb a live Studio connection)
+- if the port is held by **anything else** (e.g. an `sshd` tunnel) it refuses to
+  start and logs `PORT HIJACKED`, rather than masking the bug
+- if `ServerPackages` is missing it logs that instead of letting Rojo silently
+  exit on startup
+
+Verified by killing `rojo` and confirming the guard restored it with the port
+owned by `rojo`.
+
+**Clicking Rojo → Connect in Studio is still manual and always will be.** The
+guard keeps the *server* alive; it cannot press the button. `Rojo_autoReconnect`
+is `false` in the plugin settings, so after a drop you must reconnect by hand
+(or flip that setting in the plugin).
+
 > ⚠️ **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