Clarify reconciler --task-timeout help text

The --task-timeout help described the value as a timeout for a scheduled
task that has not been executed yet, implying a queueing deadline. The value
is passed to fetch_task_output, which uses it as an output-inactivity
timeout: it resets every time a line arrives and only fires after that many
seconds with no further output. Reword the help so operators set it for the
behaviour it actually controls.

Spell out the queued-task case explicitly rather than only denying it is a
queueing deadline: a queued task produces no output while it waits, so that
wait is not excluded from the timeout -- it counts against it in full, which
is the most likely way an operator hits it.

Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Roger Luethi <luethi@osism.tech>

Author: ideaship

osism/commands/reconciler.py

@@ -40,7 +40,12 @@ def get_parser(self, prog_name):
             "--task-timeout",
             default=os.environ.get("OSISM_TASK_TIMEOUT", 300),
             type=int,
-            help="Timeout for a scheduled task that has not been executed yet",
+            help=(
+                "Seconds to wait for further task output before giving up. "
+                "This is an output-inactivity timeout (it resets on each line). "
+                "A queued task emits no output while it waits to run, so that "
+                "wait counts against this timeout in full."
+            ),
         )
         return parser
 

tests/unit/commands/test_reconciler.py

@@ -12,6 +12,23 @@
 from osism.commands import reconciler
 
 
+def test_task_timeout_help_describes_output_inactivity():
+    cmd = reconciler.Sync(MagicMock(), MagicMock())
+    parser = cmd.get_parser("test")
+    help_text = next(
+        action.help
+        for action in parser._actions
+        if "--task-timeout" in action.option_strings
+    )
+
+    # The value bounds how long the client waits for further task output. Time
+    # a task spends queued produces no output, so it counts against the
+    # timeout rather than being excluded from it.
+    assert "output" in help_text.lower()
+    assert "scheduled task that has not been executed" not in help_text.lower()
+    assert "queued" in help_text.lower()
+
+
 def test_sync_returns_nonzero_on_task_timeout():
     cmd = reconciler.Sync(MagicMock(), MagicMock())
     parsed_args = cmd.get_parser("test").parse_args([])