fix(workflow:watch): increase poll interval to 10s and add 30min default timeout

- Increase WORKFLOWS_WATCH_INTERVAL from 5s to 10s to reduce API call rate
- Add WORKFLOWS_WATCH_MAX_CHECKS = 180 (30 min at 10s/poll) as default --checks
- Replace null/infinite default with bounded default; pass --checks=0 for no limit
- Emit a warning when the timeout is reached so users know why the command exited
- Update docblock and CHANGELOG

Prevents runaway API call volumes when workflow:watch is left running unattended
in CI/CD pipelines with no --checks limit.

Author: JGrubb

CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log
 All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org)
 
+## [Unreleased]
+
+### Changed
+
+- `workflow:watch` poll interval increased from 5s to 10s to reduce API call volume (#)
+- `workflow:watch` now times out after 180 checks (~30 minutes) by default instead of running indefinitely; pass `--checks=0` for the previous unlimited behavior (#)
+
 ## 4.2.0-rc.1 - 2026-03-18
 
 ### Added

src/Commands/Workflow/WatchCommand.php

@@ -15,7 +15,8 @@ class WatchCommand extends TerminusCommand implements SiteAwareInterface
 {
     use SiteAwareTrait;
 
-    public const WORKFLOWS_WATCH_INTERVAL = 5;
+    public const WORKFLOWS_WATCH_INTERVAL = 10;
+    public const WORKFLOWS_WATCH_MAX_CHECKS = 180;
     /**
      * @var array We keep track of workflows that have been printed. This is necessary because the local clock may
      * drift from the server's clock, causing events to be printed twice.
@@ -34,7 +35,7 @@ class WatchCommand extends TerminusCommand implements SiteAwareInterface
      *
      * @command workflow:watch
      *
-     * @option integer $checks Times to query
+     * @option integer $checks Times to query (default: 180, ~30 minutes at 10s interval). Pass 0 for no limit.
      *
      * @usage <site> Streams new and finished workflows from <site> to the console.
      *
@@ -46,12 +47,10 @@ class WatchCommand extends TerminusCommand implements SiteAwareInterface
      * @throws \Psr\Container\ContainerExceptionInterface
      * @throws \Psr\Container\NotFoundExceptionInterface
      */
-    public function watch($site_id, $options = ['checks' => null])
+    public function watch($site_id, $options = ['checks' => self::WORKFLOWS_WATCH_MAX_CHECKS])
     {
         $site = $this->getSiteById($site_id);
-        if (!is_null($number_of_checks = $options['checks'])) {
-            $number_of_checks = (int)$number_of_checks;
-        }
+        $number_of_checks = (int)$options['checks'];
 
         $this->log()->notice('Watching workflows...');
         $site->getWorkflows()->fetchWithOperations();
@@ -80,7 +79,11 @@ public function watch($site_id, $options = ['checks' => null])
                     }
                 }
             }
-            if (!is_null($number_of_checks) && (--$number_of_checks < 1)) {
+            if ($number_of_checks > 0 && (--$number_of_checks < 1)) {
+                $this->log()->warning(
+                    'Workflow watch timed out after {checks} checks. Use --checks=0 for no limit.',
+                    ['checks' => self::WORKFLOWS_WATCH_MAX_CHECKS]
+                );
                 break;
             }
         }