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

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

tools/test

@@ -1,4 +1,21 @@
 #!/usr/bin/env bash
+
+# Careful! This 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