Document reverse-SSH auth-mode mismatch and recovery

docs/ops/HYPERTWIST_REVERSE_SSH_AUTH_MODE_MISMATCH_AND_RECOVERY_2026-06-02.md

@@ -0,0 +1,39 @@
+# HyperTwist reverse-SSH auth-mode mismatch incident and recovery - 2026-06-02
+
+## Purpose
+
+This note captures a proven failure mode in the reverse-SSH Windows lane:
+transport is healthy, but non-interactive auth mode mismatch makes command
+execution look hung.
+
+## Incident signature
+
+- tunnel listener reachable (`localhost:22022`)
+- non-interactive command path fails or stalls at auth boundary
+- interactive/password-backed path succeeds
+
+## Root cause
+
+The issue is auth-mode mismatch, not tunnel transport failure.
+
+- batch path expected key/non-interactive auth
+- available path was password-interactive
+
+## Deterministic recovery
+
+1. verify tunnel reachability
+2. run fail-fast batch auth probe
+3. confirm interactive login once
+4. use bounded temporary automation if needed (`pexpect` when `sshpass`/
+   `expect` are unavailable)
+5. execute target Windows Unreal command after auth mode is confirmed
+
+## Security rule
+
+Keep credentials in sensitive runbook authorities only.
+Do not replicate passwords/keys in general ops docs.
+
+## Outcome
+
+- reverse-SSH lane remains valid
+- auth mismatch now has a deterministic diagnosis and recovery path

docs/ops/OLD_VPS_RECONSTRUCTION_INDEX_2026-05-29.md

@@ -369,3 +369,15 @@ Before live migration:
 2. archive and copy the deployed web roots, app service directories, stack
    roots, cron jobs, scripts, and cert material from the old VPS
 3. bootstrap the new host and restore the full selected role set
+
+## 2026-06-02 reverse-SSH auth-mode mismatch addendum
+
+Canonical incident packet:
+
+- [HYPERTWIST_REVERSE_SSH_AUTH_MODE_MISMATCH_AND_RECOVERY_2026-06-02.md](/home/dev/src/HyperTwist/docs/ops/HYPERTWIST_REVERSE_SSH_AUTH_MODE_MISMATCH_AND_RECOVERY_2026-06-02.md)
+
+Rule reminder:
+
+- treat transport-up and auth-ready as separate checks
+- classify auth mode before declaring a tunnel command "hung"
+- keep credential material in sensitive runbook authorities only