start fix

docs/agents/WINDOWS_AGENT.md

@@ -68,6 +68,8 @@ This matters because the maintained launcher may be run from `C:\OGP64\agent_sta
 
 Manual launches pause on fatal errors so the error remains visible. Service or scheduled-task wrappers can set `GSP_AGENT_NO_PAUSE=1` to return immediately instead of waiting forever at a `pause` prompt.
 
+The launcher now prints the detected script directory, Cygwin root, `bash.exe` path, OGP path, `ogp_agent.pl` path, config path, and startup log path before it launches the shell helper. The goal is to keep the original failure visible in the same console window instead of replacing it with a generic wrapper message.
+
 The Cygwin-side helper performs the shell work:
 
 1. enter `/OGP`
@@ -75,12 +77,14 @@ The Cygwin-side helper performs the shell work:
 3. create missing `Cfg/Config.pm`, `Cfg/Preferences.pm`, and `Cfg/bash_prefs.cfg` from tracked `.default` files
 4. strip CRLF and leading whitespace before assignments in `/OGP/Cfg/bash_prefs.cfg`
 5. source `/OGP/Cfg/bash_prefs.cfg`
-6. optionally update only the Windows agent file from Forgejo when `agent_auto_update=1`
-7. backup the current `/OGP/ogp_agent.pl`
-8. validate downloaded and installed agent files with content checks plus `perl -c`
-9. restore the backup if validation fails
-10. refuse to launch if `Cfg/Config.pm` still contains placeholder values
-11. launch `/OGP/ogp_agent.pl`
+6. set up `gsp_agent_start.log` under `/var/log` by default, or the native `C:\OGP64\var\log\gsp_agent_start.log` path when passed from the batch wrapper
+7. tee stdout and stderr to the startup log while still printing live output in the same console
+8. optionally update only the Windows agent file from Forgejo when `agent_auto_update=1`
+9. backup the current `/OGP/ogp_agent.pl`
+10. validate downloaded and installed agent files with content checks plus `perl -c`
+11. restore the backup if validation fails
+12. refuse to launch if `Cfg/Config.pm` still contains placeholder values
+13. launch `/OGP/ogp_agent.pl`
 
 Default optional update source:
 
@@ -94,6 +98,40 @@ Auto-update failure is non-fatal. Missing `curl`/`git`, download failure, clone
 
 Restart-time auto-update is allowlisted. It may replace only `/OGP/ogp_agent.pl`. It must never overwrite `Cfg/Config.pm`, `Cfg/Preferences.pm`, `Cfg/bash_prefs.cfg`, service settings, passwords, generated installer config, server homes, logs, or user-created files. Broader agent updates belong to the admin-only Panel `component_update` flow, which also preserves `Cfg/`.
 
+### Startup Log And Troubleshooting
+
+Default startup log:
+
+- `/var/log/gsp_agent_start.log` inside Cygwin
+- `C:\OGP64\var\log\gsp_agent_start.log` when launched through the Windows batch wrapper
+
+If startup fails, the batch wrapper prints the last 100 lines of that log in the same console window before pausing. This is the primary place to look for the real cause of a bad config, missing package, or bad downloaded agent file.
+
+Manual troubleshooting flow:
+
+1. Launch `agent_start.bat` directly from the Windows console or Explorer.
+2. Read the path summary printed at the top of the window.
+3. Check the log tail printed on failure.
+4. Inspect `gsp_agent_start.log` for the full startup sequence.
+
+### Auto-Update Allowlist
+
+Restart-time auto-update must not touch production config files. Only the following file is allowed to be replaced automatically:
+
+- `/OGP/ogp_agent.pl`
+
+It must never overwrite:
+
+- `Cfg/Config.pm`
+- `Cfg/Preferences.pm`
+- `Cfg/bash_prefs.cfg`
+- service settings
+- generated installer config
+- server homes
+- logs
+- user-created files
+- passwords or keys
+
 The Windows agent file does not use `DBI` at startup. If a Windows node reports `Can't locate DBI.pm` at line 48, it is a strong signal that a Linux agent file was copied onto the Windows node.
 
 Required Cygwin Perl packages include `perl`, `perl_vendor`, `perl-HTTP-Daemon`, `perl-Path-Class`, `perl-XML-Parser`, `perl-XML-Simple`, `perl-Archive-Zip`, and `perl-Archive-Extract`. A clean non-Cygwin Linux workstation may fail `perl -c` on these dependencies even though the bundled Windows Cygwin tree contains them.