tools/test [nfc]: Write down a big gotcha.

As Greg explains; see
  zulip#4700 (comment).

tools/test

@@ -1,4 +1,19 @@
 #!/usr/bin/env bash
+
+# Careful! `set -e` doesn't do everything you'd think it does. In
+# fact, we don't get its benefit in any of the `run_foo` functions.
+# That's because our logic to catch a failing suite, add it to a list,
+# and continue to the other suites, puts a bunch of commands in a list
+# before a `||`. That puts them in a special case, as the Bash manual
+# says:
+#
+# > The shell does not exit if the command that fails is [...] part of
+# any command executed in a `&&` or `||` list except the command
+# following the final `&&` or `||` [...].
+#
+# For now our workaround is to put `|| return` in the `run_foo` just
+# after each nontrivial command that isn't the final command in the
+# function.
 set -e
 
 ## CLI PARSING