[session 2] docs(guide): Command Center REBOOT flow + Hyosung applctrl gotcha (#38)

backend/src/main/resources/content/technical/agent/gotchas.md

@@ -40,3 +40,33 @@ Example — one reboot instant: agent log `14:04 CDT` = fleet DB `15:04 EDT` = `
 its institution's fleet** — if it matches the freshest cluster it's live. A whole institution
 clustered at "now minus 4h exactly" is the TZ artifact, not an outage. (The `agentConnectionStatus`
 mirror can also be stale — no reconciler.)
+
+## Command Center REBOOT: what it executes, and the Hyosung gotcha
+
+The fleet `REBOOT` task is executed agent-side by `ProcessReboot` (in `hiveops-file-collection`, driven
+by `CommandCenterModule`). The flow on a Windows ATM:
+
+1. **Go out of service** — `WindowsCommands.goOutOfService()` runs `applctrl checkupdate <timeout>`.
+   `applctrl` is **Wincor/Diebold** tooling; on a **Hyosung** ATM it does not exist
+   (`CreateProcess error=2, file not found`). Since agent **4.5.1** this missing-`applctrl` case is
+   treated as an acceptable no-op and the flow proceeds (mirrors the Linux non-Wincor path). *Before
+   4.5.1 it returned `goOutOfService=-1` and the reboot never ran on Hyosung.* (agent#82) A **real**
+   non-0/100 `applctrl` exit code still fails, so a Wincor box that legitimately refuses is not
+   force-rebooted.
+2. **Restart** — `WindowsCommands.reboot()` runs `shutdown /r /f /t 0` (forced Windows restart, no delay).
+3. The agent persists a `beforeReboot` marker, then `Thread.sleep`s waiting to be killed by the OS.
+   On a **graceful** reboot the JVM shutdown hook interrupts that sleep — this is **expected**
+   (swallowed since 4.5.1) and must NOT be reported as failure. *Before 4.5.1 the interrupt was caught
+   as FAILED and it deleted the resume marker, so a successful reboot showed FAILED.* (agent#94)
+4. On restart, `CommandProcessor` reads the persisted marker and `resumeProcessReboot` posts
+   **COMPLETED**. (A hard-killed JVM instead leaves the task RUNNING → stale re-dispatch after 5 min;
+   the graceful case is the one that needed the fix.)
+
+**Open:** there is no proper Hyosung/Nextware out-of-service command wired in yet — REBOOT currently
+force-restarts without draining. The `agent-out-of-service.cmd` script hook is the intended place to
+put a site's OOS command if one exists.
+
+**Deploying an agent fix to a box** (e.g. to verify a reboot change): a fleet `UPDATE_AGENT` task must
+use a **fleet-hosted (direct-upload) artifact** — a CDN-hosted `import-cdn` artifact 410s because the
+`UPDATE_AGENT` handler has no CDN-download path (unlike SOFTWARE/HOTFIX). The patch applies the JAR but
+does **not** auto-restart the JVM, so send a `RESTART_AGENT` before testing the new code.