fix: report tran ssh runtime timing

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

@@ -5,7 +5,7 @@ import path from "node:path";
 import { sshHelp } from "./src/help";
 import { providerTriageRecommendedCrossChecks } from "./src/provider-triage";
 import { remoteSshFrontendPlanForTest } from "./src/remote";
-import { formatSshFailureHint, parseSshArgs, parseSshInvocation, remoteApplyPatchSource, sshFailureHint } from "./src/ssh";
+import { formatSshFailureHint, formatSshRuntimeTimingHint, parseSshArgs, parseSshInvocation, remoteApplyPatchSource, sshFailureHint, sshRuntimeTimingHint } from "./src/ssh";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -264,6 +264,30 @@ export function runSshArgvGuidanceContract(): JsonRecord {
   assertCondition(formatted.startsWith("UNIDESK_SSH_HINT "), "formatted hint must have structured prefix", formatted);
   assertCondition(!formatted.includes("echo hello"), "formatted hint must not echo the original remote command", formatted);
 
+  const timingInfo = sshRuntimeTimingHint({
+    invocation: parseSshInvocation("D601:/home/ubuntu/workspace/hwlab-dev", ["argv", "true"]),
+    transport: "backend-core-broker",
+    exitCode: 0,
+    startedAtMs: 1000,
+    finishedAtMs: 5200,
+    thresholdMs: 10_000,
+  });
+  assertCondition(timingInfo.level === "info" && timingInfo.slow === false, "short ssh operation should emit an info timing hint", timingInfo);
+  assertCondition(timingInfo.elapsedMs === 4200 && timingInfo.elapsedSeconds === 4.2, "timing hint must include elapsed ms and seconds", timingInfo);
+  const slowTiming = sshRuntimeTimingHint({
+    invocation: parseSshInvocation("D601", ["apply-patch"]),
+    transport: "frontend-websocket",
+    exitCode: 0,
+    startedAtMs: 0,
+    finishedAtMs: 12_345,
+    thresholdMs: 10_000,
+  });
+  assertCondition(slowTiming.level === "warning" && slowTiming.slow === true, "slow ssh operation should emit a warning timing hint", slowTiming);
+  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("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");
   assertCondition(timeoutHint?.trigger === "timeout-or-kex", "provider session timeout must map to timeout-or-kex", timeoutHint);
 
@@ -281,6 +305,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"), "ssh help must document runtime timing hints", helpText);
 
   const crossChecks = providerTriageRecommendedCrossChecks("D601");
   assertCondition(crossChecks.includes("bun scripts/cli.ts ssh D601 argv true"), "provider triage cross-checks must keep argv true", crossChecks);
@@ -339,6 +364,7 @@ export function runSshArgvGuidanceContract(): JsonRecord {
       "post-provider k3s shorthand is rejected so location and operation stay separated",
       "k3s route stays location-only while operations fix native kubeconfig and assemble kubectl exec as argv",
       "ssh-like timeout/kex failures emit one structured argv retry hint",
+      "ssh runtime emits one structured timing hint on stderr and marks operations over 10 seconds as warnings",
       "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",