docs: clarify ssh slow timing signal

scripts/src/help.ts

@@ -178,7 +178,7 @@ export function sshHelp(): unknown {
       "Do not put operation names in any colon route segment, including nested k3s namespace/workload/container segments.",
       "Do not use post-provider shorthand such as `ssh G14 k3s ...`; write `ssh G14:k3s ...` so location and operation stay separated.",
       "If an ssh-like remote command fails with timeout/kex/exit-255 friction, stderr includes one low-noise UNIDESK_SSH_HINT JSON line with the argv retry command.",
-      "Only slow ssh/tran runtime writes UNIDESK_SSH_TIMING JSON to stderr; operations over 10s are marked level=warning and should be checked for provider latency, remote command cost, helper bootstrap, or tran/apply-patch optimization before repeating high-frequency work. Routine short calls do not emit timing noise.",
+      "Only slow ssh/tran runtime writes UNIDESK_SSH_TIMING JSON to stderr; operations over 10s are marked level=warning even when they succeed, because slow successful calls are a distributed performance monitoring signal. Check provider latency, remote command cost, helper bootstrap, or tran/apply-patch optimization before repeating high-frequency work. Routine short calls do not emit timing noise.",
       "The local tran wrapper serializes non-interactive calls per provider/plane before opening provider SSH sessions, so parallel Codex file reads do not stampede the provider session allocator; set UNIDESK_TRAN_SESSION_LOCK=0 only for explicit diagnostics.",
       "Use -- before a remote command that intentionally starts with a dash.",
     ],

scripts/ssh-argv-guidance-contract-test.ts

@@ -353,6 +353,7 @@ export function runSshArgvGuidanceContract(): JsonRecord {
   assertCondition(slowTiming.message.includes("above the 10s warning threshold"), "slow timing warning must explain the threshold", slowTiming);
   const formattedTiming = formatSshRuntimeTimingHint(slowTiming);
   assertCondition(formattedTiming.startsWith("UNIDESK_SSH_TIMING "), "formatted timing hint must have structured prefix", formattedTiming);
+  assertCondition(formattedTiming.includes("\"exitCode\":0"), "slow successful ssh operation must still emit timing warning as a performance signal", formattedTiming);
   assertCondition(!formattedTiming.includes("apply_patch"), "timing hint must not echo the original remote command", formattedTiming);
 
   const timeoutHint = sshFailureHint("D601", sshLike, 255, "unidesk ssh bridge timed out waiting for provider session");
@@ -372,7 +373,7 @@ export function runSshArgvGuidanceContract(): JsonRecord {
   assertCondition(helpText.includes("apply-patch [--allow-loose]") && helpText.includes("low-context update hunks"), "ssh help must document apply-patch loose-context guard", helpText);
   assertCondition(helpText.includes("ssh D601:k3s:hwlab-dev:hwlab-cloud-api script <<'SCRIPT'"), "ssh help must document k3s script operation", helpText);
   assertCondition(helpText.includes("UNIDESK_SSH_HINT"), "ssh help must document structured failure hint", helpText);
-  assertCondition(helpText.includes("UNIDESK_SSH_TIMING") && helpText.includes("10s") && helpText.includes("Routine short calls do not emit timing noise"), "ssh help must document slow-only runtime timing hints", helpText);
+  assertCondition(helpText.includes("UNIDESK_SSH_TIMING") && helpText.includes("10s") && helpText.includes("slow successful calls are a distributed performance monitoring signal") && helpText.includes("Routine short calls do not emit timing noise"), "ssh help must document slow-only runtime timing hints", helpText);
   assertCondition(helpText.includes("UNIDESK_TRAN_SESSION_LOCK=0") && helpText.includes("provider session allocator"), "ssh help must document tran provider session serialization", helpText);
 
   const crossChecks = providerTriageRecommendedCrossChecks("D601");
@@ -439,7 +440,7 @@ export function runSshArgvGuidanceContract(): JsonRecord {
       "k3s route stays location-only while operations fix native kubeconfig and assemble kubectl exec as argv",
       "top-level remote option parsing preserves command-local -- separators for script -- sed -n style commands",
       "ssh-like timeout/kex failures emit one structured argv retry hint",
-      "ssh runtime emits structured timing only for slow operations over 10 seconds",
+      "ssh runtime emits structured timing for slow operations over 10 seconds, including successful slow calls",
       "help text documents stdin script passthrough and UNIDESK_SSH_HINT",
       "provider triage recommendedCrossChecks keeps ssh D601 argv true",
       "remote frontend ssh uses the same structured route parser for host, k3s and pod argv routes",