[#961] Clarify Operator MCP VPS loopback and SSH forwarding troubleshooting

[realproject7]

Closes #961

Summary

Docs-only. The Operator MCP VPS path in docs/operator-mcp.md was technically correct but easy to misread during troubleshooting (surfaced while recovering a PlotLink OWS operator session). Adds a focused Remote / VPS troubleshooting subsection directly under the existing Remote / VPS registration section — it references that section rather than duplicating its commands.

New content:

• Restates the loopback rule: quadwork-mcp-operator --port 8400 always connects to 127.0.0.1:8400 of the machine running the command.
• "Expected failures": nc -vz <vps-ip> 8400 refused (and a browser to http://<vps-ip>:8400 failing) is normal when the backend binds VPS loopback only; do not open 8400 publicly to "fix" it (security regression) — forward over SSH instead.
• The exact copy-pasteable tunnel command: ssh -N -L 8400:127.0.0.1:8400 <ssh-alias-or-user@vps>.
• A bottom-up verify checklist (ssh -G, lsof -iTCP:8400 -sTCP:LISTEN, quadwork-mcp-operator).
• Warns that ssh <ip> and ssh <alias> can resolve to different users/identity files — verify with ssh -G before assuming you're hitting the intended VPS login.
• A symptom → cause → fix table.
• Notes why the stdio JSON-RPC examples carry a trailing sleep (keep stdin open so the server flushes responses before the pipe closes).

EPIC Alignment

EPIC #967 — folded / isolated (per the batch brief). Docs-only, low risk; no epic-tracked surface touched.

Self-Verification

Adversarial diff re-read — the diff is confined to docs/operator-mcp.md: one new ### Remote / VPS troubleshooting subsection + a one-paragraph note in the stdio intro. No other file changed.

Kill-list / safety invariants:

• Docs-only, no code/behavior change — only a .md file changed (git status shows just docs/operator-mcp.md).
• Does not contradict existing content — the new subsection restates and references the Registration section (#remote--vps-registration) and the stdio examples (#direct-stdio-json-rpc-invocation); the -N -L tunnel is a refinement of the existing -L example, not a conflicting instruction.
• pack-smoke passes.

Build + test evidence:

• node server/pack-smoke.test.js → PASS (24 shipped Node files, 11 runtime assets).
• Rendered the new section — table well-formed; both intra-doc anchor links resolve (#remote--vps-registration, #direct-stdio-json-rpc-invocation).

Acceptance criteria (1:1):

• Distinguishes SSH-to-VPS working / direct <vps-ip>:8400 failing normally / local forwarded 127.0.0.1:8400 working ✅
• Copy-pasteable -N -L SSH tunnel command ✅
• Explains why opening 8400 publicly is not the right fix ✅
• Calls out SSH alias vs direct-IP user/identity differences ✅
• Direct stdio examples remain accurate and mention response-wait timing (the sleep note) ✅

Deviations

None.

[realproject7]

@re2 APPROVE at 39d0723c581fe30660f45ba70b90187126ab16f4

Docs-only, exactly one file (docs/operator-mcp.md, +43/−0). No code or behavior change.

Checked (evidence)

• Scope is docs-only. Sole changed file is docs/operator-mcp.md; the diff adds a ### Remote / VPS troubleshooting subsection (L87) plus a trailing-sleep explanatory note (L149). No source/config touched.
• No contradiction with existing content — it reinforces it. The new subsection's core claim ("quadwork-mcp-operator --port 8400 always connects to 127.0.0.1 of the machine running the client; direct VPS-IP is deliberately closed; use an SSH tunnel") matches the pre-existing Registration text at L71/L80/L85 ("the loopback of whatever machine the MCP client runs on… Use SSH or a port-forward"). It references the Registration section rather than duplicating it.
• Both intra-doc anchors resolve. #remote--vps-registration → ### Remote / VPS registration (L69); #direct-stdio-json-rpc-invocation → ## Direct stdio JSON-RPC invocation (L126). GitHub slugging confirmed (space→-, /→dropped, so / → --).
• Covers all four issue Clarify Operator MCP VPS loopback and SSH forwarding troubleshooting #961 confusion points: (1) client hits the client-machine's 127.0.0.1; (2) <vps-ip>:8400 refused is EXPECTED under loopback-only bind + explicit "do NOT open 8400 publicly" security note; (3) exact tunnel ssh -N -L 8400:127.0.0.1:8400 <alias-or-user@vps> (or run client over SSH on the VPS); (4) a symptom→cause→fix table. Plus the useful ssh <ip> vs ssh <alias> identity-mismatch warning and a bottom-up ssh -G/lsof/client verify checklist. Commands are correct and safe.
• Placement is sensible — troubleshooting immediately follows Registration; markdown table is well-formed.

One flag for the operator gate: gh pr checks 996 shows test pending at review time — content APPROVE stands (docs-only, no runtime surface), just confirm the run goes green before merge. state OPEN, mergeable MERGEABLE, head unmoved.

No blocking issues. Standing no-merge rule — operator merges.

[project7-interns]

Verdict: APPROVE

Epic Alignment: PASS

Docs-only #961 closes the folded #967 Operator MCP clarification item without touching code, behavior, config, or runtime contracts.

Checked (evidence)

• Structural gate: PR body contains filled ## EPIC Alignment, ## Self-Verification, and ## Deviations.
• Issue/epic context: gh issue view 961 + gh api repos/realproject7/quadwork/issues/967; #961 asks only for clearer VPS loopback/SSH-forwarding troubleshooting.
• Live diff scope: gh api repos/realproject7/quadwork/pulls/996/files → exactly docs/operator-mcp.md (+43).
• Existing registration context preserved: docs/operator-mcp.md:69-85 still states the client-machine loopback rule and registration options.
• New troubleshooting coverage: docs/operator-mcp.md:87-124 covers expected public-IP refusal, do-not-open-8400 guidance, -N -L tunnel, bottom-up checks, SSH alias-vs-IP identity, and symptom/cause/fix table.
• Stdio timing clarification: docs/operator-mcp.md:150-152 explains the trailing sleep behavior requested by #961.
• Riskiest part of this diff: docs could imply exposing 8400 is acceptable; acceptable because docs/operator-mcp.md:93-94 explicitly says refusal is expected and public exposure is the wrong fix.
• Kill-list: scanned all items — clean for docs-only scope.
• CI: gh pr checks 996 → test pass 58s.

Findings

• None.

Decision

Approve at 39d0723c581fe30660f45ba70b90187126ab16f4. The patch is confined to the requested doc and directly covers every #961 acceptance point without duplicating the registration section or changing behavior.