Print a hosted-proof watch command (#41)

Print a strict, host-bound gh command for following the exact dispatched run's progress and final status. The run URL remains the route to the bounded result; dispatch and containment are unchanged.

TRY_IT.md

@@ -33,8 +33,10 @@ python (Join-Path $proofDir "scripts\start_hosted_proof.py") `
 ```
 
 The helper prints the exact workflow-run URL when GitHub returns it directly or
-the helper can uniquely correlate it to this dispatch. Open that URL to watch
-the proof and read its bounded result.
+the helper can uniquely correlate it to this dispatch. For an exact run URL it
+also prints a copyable `gh run watch` command, so you can follow the workflow's
+progress and final status without leaving the terminal. Open the run URL to read
+the bounded result.
 
 ### Or use the GitHub interface
 

src/lumi_eggcracker/hosted_proof.py

@@ -22,7 +22,11 @@ RESULT_FORM_URL = (
 )
 REVIEWED_WORKFLOW_BLOB = "3761d8c3b29f1265e402c788e5340f6eab2c70df"
 ACKNOWLEDGEMENT = "i_understand_this_kills_a_test_tree=true"
-RUN_URL = re.compile(r"^https://github\.com/[^/]+/[^/]+/actions/runs/[1-9][0-9]*$")
+RUN_URL = re.compile(
+    r"^https://github\.com/"
+    r"(?P<owner>[A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))/"
+    r"Lumi-Eggcracker/actions/runs/(?P<run_id>[1-9][0-9]*)$"
+)
 CORRELATION_ID = re.compile(r"^[0-9a-f]{32}$")
 RUN_NAME_PREFIX = "Containment probe"
 RUN_LOOKUP_ATTEMPTS = 3
@@ -44,6 +48,16 @@ class HostedProofError(RuntimeError):
     """A bounded, user-actionable hosted-proof startup failure."""
 
 
+def _watch_command(url: str) -> str | None:
+    """Return a copyable command only for an exact validated hosted-proof run URL."""
+
+    match = RUN_URL.fullmatch(url)
+    if match is None:
+        return None
+    repository = f"{HOST}/{match.group('owner')}/{REPOSITORY_NAME}"
+    return f"gh run watch {match.group('run_id')} --repo {repository} --exit-status"
+
+
 def _default_runner(
     command: Sequence[str],
     *,
@@ -405,5 +419,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     except HostedProofError as error:
         parser.error(str(error))
     print(f"Hosted proof dispatched: {url}")
+    watch_command = _watch_command(url)
+    if watch_command is not None:
+        print(f"Watch from this terminal: {watch_command}")
     print(f"After it finishes, share the public run or friction: {RESULT_FORM_URL}")
     return 0

tests/test_hosted_proof.py

@@ -143,6 +143,61 @@ class HostedProofTests(unittest.TestCase):
 
         self.assertEqual(0, status)
         starter.assert_called_once_with(acknowledged=True)
+        self.assertEqual(
+            [
+                f"Hosted proof dispatched: {url}",
+                (
+                    "Watch from this terminal: "
+                    "gh run watch 123 --repo github.com/operator/Lumi-Eggcracker "
+                    "--exit-status"
+                ),
+                (
+                    "After it finishes, share the public run or friction: "
+                    f"{hosted_proof_module.RESULT_FORM_URL}"
+                ),
+            ],
+            output.getvalue().splitlines(),
+        )
+
+    def test_watch_command_requires_exact_safe_github_run_url(self) -> None:
+        self.assertEqual(
+            (
+                "gh run watch 123 --repo github.com/operator/Lumi-Eggcracker "
+                "--exit-status"
+            ),
+            hosted_proof_module._watch_command(
+                "https://github.com/operator/Lumi-Eggcracker/actions/runs/123"
+            ),
+        )
+        rejected = (
+            "http://github.com/operator/Lumi-Eggcracker/actions/runs/123",
+            "https://gitlab.com/operator/Lumi-Eggcracker/actions/runs/123",
+            "https://github.com/operator/other/actions/runs/123",
+            "https://github.com/operator/Lumi-Eggcracker/actions/runs/0",
+            "https://github.com/operator/Lumi-Eggcracker/actions/runs/123?x=1",
+            "https://github.com/operator/Lumi-Eggcracker/actions/runs/123#fragment",
+            "https://github.com/bad;name/Lumi-Eggcracker/actions/runs/123",
+        )
+        for url in rejected:
+            with self.subTest(url=url):
+                self.assertIsNone(hosted_proof_module._watch_command(url))
+
+    def test_cli_omits_watch_command_for_fallback_workflow_page(self) -> None:
+        url = (
+            "https://github.com/operator/Lumi-Eggcracker/actions/workflows/"
+            "containment-probe.yml"
+        )
+        output = StringIO()
+        with (
+            patch.object(hosted_proof_module.shutil, "which", return_value="gh"),
+            patch.object(hosted_proof_module, "start_hosted_proof", return_value=url),
+            redirect_stdout(output),
+        ):
+            status = hosted_proof_module.main(
+                ["--i-understand-this-kills-a-test-tree"]
+            )
+
+        self.assertEqual(0, status)
         self.assertEqual(
             [
                 f"Hosted proof dispatched: {url}",