feat: terminal launcher diagnostics and mutation preflight (Closes #556)

Add categorize-and-probe helpers for shell spawn failures, expose
gitea_diagnose_terminal, and fail closed on mutation capability resolve
when the terminal launcher is unhealthy (BLOCKED + DIAGNOSE). Document
the operator path in the workflow runbooks.

tests/test_resolve_task_capability.py

@@ -96,6 +96,14 @@ class TestResolveTaskCapability(unittest.TestCase):
             "GITEA_TOKEN_MERGER": "merger-pass",
         }
 
+    def test_diagnose_terminal_success_has_no_error(self):
+        res = mcp_server.gitea_diagnose_terminal(
+            command=[sys.executable, "-c", "raise SystemExit(0)"]
+        )
+        self.assertTrue(res["healthy"])
+        self.assertIsNone(res["error_type"])
+        self.assertEqual(res["error_msg"], "")
+
     @patch("mcp_server.api_request", return_value={"login": "author-user"})
     @patch("mcp_server.get_auth_header", return_value="token author-pass")
     def test_resolve_author_capable_task(self, _auth, _api):
@@ -110,6 +118,39 @@ class TestResolveTaskCapability(unittest.TestCase):
             self.assertFalse(res["different_mcp_namespace_required"])
             self.assertIn("ready for operations", res["exact_safe_next_action"])
 
+    @patch("mcp_server.native_mcp_preference.probe_terminal_spawn")
+    @patch("mcp_server.api_request", return_value={"login": "author-user"})
+    @patch("mcp_server.get_auth_header", return_value="token author-pass")
+    def test_resolve_mutation_task_blocks_when_terminal_launcher_unhealthy(
+        self,
+        _auth,
+        _api,
+        mock_probe,
+    ):
+        mock_probe.return_value = {
+            "healthy": False,
+            "error_type": "missing cwd",
+            "error_msg": "Current working directory does not exist: /missing",
+            "cwd": "/missing",
+            "command": ["git", "--version"],
+            "diagnostics": {"cwd_exists": False},
+        }
+        env = self._env("author-profile")
+        # Probe is skipped under pytest unless forced (mirrors production path).
+        env["GITEA_FORCE_TERMINAL_PROBE"] = "1"
+        with patch.dict(os.environ, env):
+            res = mcp_server.gitea_resolve_task_capability(task="create_issue", remote="prgs")
+
+        self.assertFalse(res["allowed_in_current_session"])
+        self.assertTrue(res["stop_required"])
+        self.assertTrue(res["infra_stop"])
+        self.assertTrue(res["terminal_launcher_unhealthy"])
+        self.assertTrue(res["blocked"])
+        self.assertEqual(res["blocked_reason"], "BLOCKED + DIAGNOSE")
+        self.assertEqual(res["terminal_launcher_diagnostics"]["error_type"], "missing cwd")
+        self.assertIn("terminal-launcher-failure", res["exact_safe_next_action"])
+        self.assertIn("BLOCKED + DIAGNOSE", res["exact_safe_next_action"])
+
     @patch("mcp_server.api_request", return_value={"login": "author-user"})
     @patch("mcp_server.get_auth_header", return_value="token author-pass")
     def test_resolve_reviewer_capable_task_blocked(self, _auth, _api):