+# Mimics GNU timeout, but has special modes which gather test result data and retry failed tests.
+
+######################################### How this works ##########################################
+#
+# Because we have several different test harnesses and we don't invoke them directly, communication
+# between this script and the harness is done through the simplest means possible (environment
+# variables to communicate babysitter->harness, files in standard locations harness->babysitter).
+#
+# The script supports three different ways of extracting test data from the invoked test suite:
+#
+# 1. "The babysitter protocol": The babysitter sets five environment variables (see below):
+# "Ran test file": A path to a file where the harness should write a line-delimited list of
+# tests which ran to completion.
+# "Failed test file": A path to a file where the harness should write a line-delimited list
+# of tests that failed.
+# "Current test file": A path to a file where the harness should write the currently running
+# test before a test begins, then delete afterward (used to detect early termination).
+# "Run test": A list of test names, used by:
+# "Run mode": This is either RUN or EXCLUDE. If RUN, the test list is a whitelist; run only
+# those tests. If EXCLUDE, the list is a blacklist; run all except those tests.
+# This is the most featureful mode: It can report where we failed in the case of timeouts or
+# crashes that take down the harness, and if the feature is enabled it can retry failed tests.
+# However, it requires modification to the test harness.
+#
+# 2. NUnit XML: The babysitter also sets a sixth environment variable:
+# "XML list file": A path to a file where the harness should write a line-delimited list of
+# paths to NUnit-format XML result files it created.
+# This also requires modification to the test harness, but less of it.
+#
+# 3. NUnit XML (manually specified): If the test harness can't be modified, but the caller of the
+# babysitter script happens to know where the harness writes its result XML files, the caller
+# can specify those paths in the "Extra XML" environment variable (see --help)
+#
+# A single babysitter invocation can currently handle either the babysitter protocol or the XML,
+# but never a mix of the two.
+#
+###################################################################################################